TUASESOR Repository Guide

This document is the authoritative guide to repository organization, navigation, and code placement for TUASESOR. It describes the current tracked repository; it does not replace the architectural, persistence, ecosystem, or onboarding sources linked below.

Repository Purpose And Scope

This repository contains a single Next.js App Router application, its reusable React UI, directly owned server modules, Supabase database assets, repository tooling, canonical technical documentation, and a separate Docusaurus documentation-site toolchain. The active server module areas are Google authentication and Drive integration, authorized workspace discovery, and the expense-report domain, including listing, detail, initial draft creation, catalog reads, item totals, and secure item create/update/delete operations while reports remain draft. Cortexa packages are consumed as local dependencies, but their implementations are outside this repository.

Use this guide to locate code and decide where a change belongs. Use ARCHITECTURE.md for responsibilities and system boundaries, DATABASE.md for persistence details, ECOSYSTEM.md for product/platform ownership, and README.md for setup and common commands.

Organization Model

The repository uses a hybrid organization:

• Next.js framework entry points and route composition live under app/.
• Reusable presentation code is separated into components/ and hooks/.
• Small cross-cutting helpers and runtime-specific Supabase client factories live under lib/.
• Server modules are grouped by responsibility or domain under server/.
• Database history, validation assets, exports, and database tooling live under database/.
• Canonical documentation, generated references, and publication-site source are kept distinct under docs/ and documentation/.

This is not a runtime package monorepo. The root package is the TUASESOR application, while documentation/ has separate package metadata only for the Docusaurus site. Shared Cortexa implementations referenced through file: dependencies are external repository boundaries, not source areas within this checkout.

For organization and placement questions, use the following evidence order:

1. Current tracked structure, implementation, and imports.
2. Current package and repository scripts.
3. This document.
4. ARCHITECTURE.md, DATABASE.md, and ECOSYSTEM.md for their respective concerns.
5. The generated project tree.
6. README.md and synchronized publication copies.

An approved source document may record a newer deliberate decision, but directory names, generated output, local-only folders, and older prose do not by themselves establish an active module.

Repository Map

.
|-- app/                  Next.js routes, layouts, callbacks, and API handlers
|   |-- (app)/            Shared application-shell route group
|   |-- api/              HTTP route handlers
|   `-- <route>/          Direct route segments and auth callback
|-- components/           Shared and feature-oriented React presentation
|   |-- ui/               Reusable UI primitives
|   |-- layout/           Application shells and navigation
|   `-- providers/        Client-side React providers
|-- hooks/                Reusable browser-facing React hooks
|-- lib/                  Small shared helpers and Supabase client factories
|-- server/               Server-only domains, auth adapters, and connectors
|-- database/             Migrations, rollback, tests, seeds, exports, and tools
|-- docs/                 Canonical and generated repository documentation
|-- documentation/        Docusaurus site and synchronized documentation copies
|-- scripts/              Repository maintenance and documentation automation
`-- root files            Runtime middleware, package metadata, and tool config

For deeper structural navigation, use repository/project-tree.md. It is a generated checkout snapshot, not an exhaustive responsibility map or proof that every listed directory is tracked and active.

Top-Level Area Responsibilities

app/

app/ is the Next.js runtime and HTTP-entry area. Pages, layouts, route groups, loading or error boundaries, redirects, authentication callbacks, global styles, and API route.ts files belong here. Reusable UI belongs in components/; reusable business, provider, credential, or persistence behavior belongs in a controlled server module rather than a page or route handler.

Code under app/ can execute in different runtimes. A file is not browser-safe merely because it is under app/, and a client component must not runtime-import server-only code.

components/

components/ owns React presentation shared by routes or meaningful parts of the application. It contains generic UI primitives, shell and navigation components, workspace-related providers, and feature presentation. It must not contain privileged persistence, provider credentials, OAuth token operations, or authorization-sensitive business logic.

hooks/

hooks/ contains reusable React hooks for browser and component behavior. It is not a server data-access or provider-integration area.

lib/

lib/ contains small cross-cutting helpers and framework integration helpers that do not justify a domain module. The established Supabase subarea separates browser, server, and middleware client construction. Feature-specific business rules, large adapters, and persistence repositories do not belong here.

server/

server/ owns application-specific server modules: domain services and repositories, provider configuration, authentication orchestration, storage adapters, and connector factories. It is imported by server-side route and provider-callback paths, not by browser runtime code. Request middleware uses its separate server-side helper under lib/supabase/.

The service/repository pattern is established for expense reports, while authentication uses controller, provider, service, and storage-adapter subareas. These patterns are real but not universal: some server-only callbacks, middleware, and route handlers still perform narrowly scoped Supabase queries directly.

database/

database/ owns database change history and database-specific tooling. Forward migrations, rollback aids, SQL validation, seeds, exceptional data-loading scripts, generated schema exports, and export generators belong here. Runtime TypeScript and React code do not.

docs/

docs/ is the canonical technical documentation area. Its primary Markdown sources are manually maintained, while docs/repository/project-tree.md and the schema references under docs/database/ are generated. Application code, secrets, local state, and documentation-site UI do not belong here.

documentation/

documentation/ is a separate Docusaurus application used to browse and publish documentation. Its configuration, site pages, blog content, styles, and static assets belong here. The selected files under documentation/docs/ are synchronized copies and do not override their sources in the root README.md or docs/.

The root TypeScript project excludes this directory; the site has its own package metadata, lockfile, and TypeScript configuration.

scripts/

scripts/ contains tracked, reusable repository maintenance and documentation automation. Database-specific tooling remains under database/scripts/. Production runtime modules and one-off local command notes do not belong in either scripts area.

Root-Level Artifacts

The root package.json and lockfile define the application dependency graph and common commands. Root Next.js, TypeScript, Tailwind, PostCSS, and component configuration files configure the application toolchain. middleware.ts is runtime request middleware, and README.md is the repository entry point.

Feature code should not be added at the repository root. Framework-generated or compiler-generated root files are not locations for handwritten application behavior.

Application And Routing Organization

The repository follows Next.js App Router file conventions:

• app/layout.tsx, app/page.tsx, app/loading.tsx, and app/globals.css define root composition, entry behavior, loading UI, and global styling.
• app/(app)/ is a route group with a shared application shell. Parentheses organize routes without becoming a URL segment.
• Direct app/<segment>/page.tsx routes also exist. Several use the reusable components/layout shell, while the route group composes its shell in app/(app)/layout.tsx. Extend the shell used by the containing route rather than introducing a third shell pattern.
• app/api/<area>/route.ts files are HTTP boundaries. They own request parsing, status codes, response projection, and HTTP-specific error handling.
• app/auth/callback/route.ts handles the application authentication callback. Provider connection routes under app/api/auth/ are a distinct flow and delegate to server auth modules.

Route-local presentation may remain beside a page when it is used only by that route. Move it to components/<feature>/ when it becomes reusable or substantial enough to have a stable presentation responsibility.

No tracked error.tsx boundary currently exists. If one is needed, place it in the affected App Router segment according to Next.js conventions; do not create a separate error-handling top-level area.

API handlers should remain focused on HTTP orchestration when reusable server boundaries exist. The current workspace-discovery and expense-report handlers delegate reusable validation, authorization-sensitive orchestration, persistence mapping, and RPC access to controlled server or database boundaries. Expense-report APIs cover listing, detail, initial draft creation, catalog reads, and individual item creation, update, and deletion. Google auth handlers delegate to an auth controller. A provider flow that is currently implemented inside a server-only route remains server-side, but reusable behavior should move behind the applicable server/ boundary instead of being copied into another route.

The current middleware excludes /api/ paths from page admission checks. Each protected API must therefore establish the authentication, profile, workspace, and ownership checks required by that operation within its route, service, repository, and database controls.

UI And Component Organization

The component areas have distinct placement roles:

• components/ui/ contains generic shadcn/Radix-style primitives used throughout the application.
• components/layout/ contains application shells, sidebars, headers, navigation, workspace switching presentation, and other layout composition.
• components/providers/ contains client-side React context providers.
• Feature directories such as components/calendar/ and components/dashboard/ contain presentation reusable within a feature.
• Small application-wide presentation components may live directly under components/ when no narrower durable area applies.

Use a route directory for page-only composition. Use components/<feature>/ when a component is reused, has its own meaningful presentation behavior, or would make a route file responsible for too much UI detail. Use components/ui/ only for product-agnostic primitives; product terminology and workflow state normally indicate a feature or layout component.

Client components declare "use client" when they use state, effects, context, navigation hooks, browser APIs, or client-only UI libraries. Client-side workspace context is presentation and request context, not authorization proof. Browser components may call application APIs or use the public/session-aware browser Supabase factory where appropriate, but they must not receive provider credentials or perform privileged persistence.

Server-Side Organization

The current server organization is responsibility-oriented:

• server/expense-reports/ separates domain types, report and item validation, workflow orchestration, catalog and detail loading, and Supabase query/RPC mapping between a service and repository. This module owns the current server-side application boundary for report listing, detail, initial draft creation, item totals, and secure item create/update/delete operations.
• server/auth/google/ owns Google auth request/callback control flow.
• server/auth/providers/ owns provider construction and server-side credential configuration.
• server/auth/services/ composes Cortexa auth behavior with TUASESOR dependencies.
• server/auth/storage/ implements the Supabase-backed Cortexa auth storage contract.
• server/connectors/ constructs provider connectors consumed by server flows.

Place reusable business validation and orchestration in a domain service. Place domain persistence queries and mappings in that domain's repository when the repository pattern exists. Place a provider-specific implementation behind the relevant auth, storage, or connector boundary.

Authentication callbacks, middleware, and API routes are also controlled server boundaries. Direct database access there is limited to their boundary-specific responsibilities in the current code; it does not establish presentation-layer database access as a convention.

There is no tracked worker, queue, scheduler, or background-job area. Introducing one is a runtime and repository design decision, not a reason to place long-running behavior in an arbitrary route or script.

Shared Libraries And Local Packages

Use lib/ for small helpers shared across areas:

• lib/utils.ts provides general presentation utility behavior.
• lib/supabase/client.ts constructs the browser client.
• lib/supabase/server.ts constructs the cookie-aware server client.
• lib/supabase/middleware.ts owns request-session refresh and profile admission in middleware.

Select the helper that matches the execution runtime. The root-level lib/supabase-client.ts has no tracked imports and does not establish a second preferred Supabase client convention.

Use hooks/ for reusable React behavior, not framework-agnostic utilities or server access. Keep a helper inside its feature until more than one area has a stable need for it.

The repository has no packages/ workspace. Cortexa dependencies are declared as local file: dependencies in the root package manifest, but their source remains outside TUASESOR. Product-specific adapters and orchestration belong in server/; reusable cross-product capability belongs in its owning Cortexa repository only after an explicit ownership decision. Consult ECOSYSTEM.md and ARCHITECTURE.md before promoting or duplicating a capability.

There is no general shared-contract directory. Server domain types currently live with their domain, and one client page uses a type-only import from that area. A new contract used across runtimes or repositories requires an explicit placement and ownership decision rather than an invented top-level folder.

Database And Migration Organization

Database artifacts are separated by purpose:

• database/migrations/ contains ordered, incremental forward migrations with three-digit numeric prefixes.
• database/rollback/ contains explicitly named rollback SQL kept separate from forward history. The single tracked rollback is paired to a migration by number and _rollback.sql; this is limited evidence, not a universal rollback framework.
• database/tests/ contains SQL validation assets. These are not application unit tests and are not wired to a root test command.
• database/seeds/ contains seed SQL. Older seeds must be checked against later migrations before use.
• database/real-data/ contains an exceptional tracked data-loading script. Its presence does not make real or production data an acceptable fixture convention; new use requires explicit review and must never include credentials or secrets.
• database/scripts/ contains schema export and Markdown-generation tooling.
• supabase/config.toml contains the tracked local Supabase CLI configuration used by the repository staging workflow.
• supabase/migrations/ and supabase/seed.sql are generated local staging artifacts derived from canonical repository assets. They are not the source of truth and must not be edited manually.
• database/schema/schema.sql and database/schema/schema.md are generated structural exports.
• database/schema.dbml is not generated by the current export workflow and is superseded by the current migration/export model.

Forward database changes belong in a new incremental migration; do not rewrite applied history merely to make an old file resemble current state. A rollback aid, when justified, remains separate and must be reviewed against current security and data-loss consequences. Runtime repositories that query persistence remain under server/, not beside SQL migrations.

npm run db:schema runs database/scripts/export-schema.ps1 and refreshes both database/schema/ and docs/database/. These generated copies must not be edited manually. Schema design, grants, RLS, migration replayability, and rollback implications belong in DATABASE.md, not in this guide.

Documentation Organization

Documentation has three distinct roles:

1. Canonical sources: README.md, the primary documents in docs/, manually maintained references under docs/references/, and explanatory material such as docs/database/data-dictionary.md.
2. Generated references: docs/repository/project-tree.md and the generated schema files under docs/database/.
3. Publication site: the Docusaurus application under documentation/, including synchronized copies under documentation/docs/.

Edit the canonical source first. scripts/sync-docusaurus-docs.ps1 copies the root README and a selected set of docs/ sources into documentation/docs/, adjusting links for the site. Run or review that workflow when publication copies are in scope; do not treat the copies as independent authorities.

scripts/generate-project-tree.ps1 generates docs/repository/project-tree.md; regenerate it with:

npm run docs:tree

The tree is a structural navigation snapshot. It must not be edited manually, does not define ownership or code placement, and does not replace this guide. The generator scans the checkout after applying exclusions rather than asking Git for tracked files, so local or empty directories can appear; verify tracked state and imports before treating a tree entry as active.

The schema export workflow generates identical structural copies under database/schema/ and docs/database/. The Docusaurus sync then copies the publishable Markdown schema reference, not the SQL export, into the site.

Scripts And Maintenance Tooling

Tracked repository-wide helpers belong under scripts/. The current scripts support local development cleanup/startup, project-tree generation, and documentation synchronization. They are developer tools, not production runtime modules.

Database export and schema-document generation belong under database/scripts/ because they operate on database artifacts and update database documentation. Documentation-site build commands belong in documentation/package.json, while root application and repository commands belong in the root package manifest.

A script should be tracked only when it is intentionally reusable and its scope, inputs, outputs, and side effects are reviewable. Temporary diagnostics and machine-specific troubleshooting commands do not establish repository conventions and should not be committed as durable tooling.

Dependency And Placement Boundaries

The current organization supports these repository-level rules:

• Browser UI depends on reusable UI, hooks, browser-safe helpers, and application HTTP boundaries. It must not runtime-import server/ modules.
• Route handlers and callbacks own HTTP concerns. They delegate reusable validation, persistence, auth, and provider behavior when an established server boundary applies.
• Domain services may depend on domain types and repositories; repositories own domain-specific Supabase query and mapping details.
• Provider configuration, token refresh, credential persistence, and connector construction remain behind server-side auth, storage, service, or connector boundaries.
• Runtime-specific Supabase factories must not be interchanged casually. Browser code uses public/session-aware configuration; server and middleware code use cookie-aware server clients.
• Client-selected profile or workspace values are request context only. Authorization remains in authenticated server paths and database controls.
• Database migrations and SQL tests do not import or depend on application runtime code.
• Generated schema and repository-tree files describe structure; they do not define runtime behavior, ownership, or dependency direction.
• documentation/docs/ mirrors selected source documents and cannot override docs/.
• TUASESOR adapters may depend on Cortexa packages. Cortexa packages must not depend on TUASESOR internals, and TUASESOR must not silently duplicate platform-owned behavior.

Code Placement Guidance

Change	Preferred placement	Placement rule
New page or product route	app/(app)/<segment>/page.tsx when it belongs to the shared application shell; otherwise the relevant existing app/<segment>/	Extend the route's current shell and colocate page-only composition. Do not assume direct route segments are public or create a new shell pattern.
New API route handler	app/api/<area>/route.ts	Keep HTTP parsing, response mapping, and status handling here; delegate reusable behavior to server/.
New reusable UI primitive	components/ui/	Use for generic, product-agnostic building blocks consistent with the existing shadcn/Radix primitives.
New feature-specific UI	components/<feature>/ or the owning route	Colocate single-use UI with the route; move it to a feature component area when it has a stable reusable presentation responsibility.
New layout, navigation, or shared provider	components/layout/ or components/providers/	Keep shell composition separate from domain services and privileged access.
New server-side business service	server/<domain>/<domain>.service.ts	Put reusable validation and workflow orchestration here when the established domain pattern fits.
New persistence repository	server/<domain>/<domain>.repository.ts	Keep domain queries, RPC calls, and persistence mapping together and use an authenticated Supabase client supplied by a server boundary.
New external-provider adapter	server/connectors/, server/auth/, or a new responsibility-specific server subarea	Choose by responsibility: connector construction, auth orchestration, or credential storage. Do not place provider SDK or token logic in UI.
New authentication or authorization behavior	middleware.ts, lib/supabase/middleware.ts, an auth callback/route, or server/auth/	Use the narrow boundary matching admission, session, provider authorization, or storage. Cross-cutting changes require review against architecture and database controls.
New workspace-scoped workflow	Owning app/api/ route plus server/<domain>/ service/repository	Treat the client workspace selection as input, then authenticate and enforce membership/authorization in server and persistence boundaries.
New database migration	database/migrations/<next-number>_<description>.sql	Add an incremental, traceable forward change and review DATABASE.md.
New rollback script	database/rollback/	Pair it clearly with the affected migration, keep it separate from forward history, and document weaker security or destructive consequences in the script.
New shared utility or hook	lib/, hooks/, or the owning feature	Use lib/ for small cross-cutting helpers, hooks/ for reusable React behavior, and feature colocation until sharing is real.
New local reusable package	No established in-repository location	The repository has no runtime package workspace. Adding one requires an explicit repository and ownership decision.
New Cortexa integration	TUASESOR adapter/orchestration under server/; package implementation in its owning external repository	Confirm capability ownership in ECOSYSTEM.md; do not copy shared package internals into TUASESOR.
New canonical documentation source	docs/, or root README.md for landing/onboarding	Choose the existing source-of-truth responsibility and avoid duplicating another document.
New generated documentation artifact	A deliberate output path under docs/ plus a tracked generator under scripts/ or database/scripts/	Add a generated notice, deterministic regeneration command, and clear source relationship. This requires an explicit workflow decision.
New documentation-site page	documentation/src/pages/, documentation/blog/, or site configuration as appropriate	Use for site-only publication content; canonical technical docs remain under docs/ and are synchronized.
New maintenance script	scripts/ or database/scripts/	Track only durable reusable automation; keep production runtime behavior in application code.

Sensitive And Security-Relevant Code Placement

Keep sensitive behavior within the narrow server-side boundary that owns it:

• OAuth authorization codes, access tokens, refresh tokens, token refresh, and provider-account persistence belong in server auth routes, services, providers, and storage adapters.
• Provider client secrets and other service credentials belong in server runtime configuration. They must never be committed, copied into client components, embedded in generated artifacts, or written into documentation.
• Browser Supabase clients may use intentionally public connection values and the signed-in user session. Privileged or service-level access, if introduced, must stay server-side and must not replace user-context authorization in ordinary flows.
• Profile admission and workspace authorization belong in middleware, server services/routes, repositories, migrations, grants, and RLS-aware persistence paths as applicable. Client context, query parameters, and hidden controls are not authorization.
• RLS policies, grants, functions, and schema controls belong in incremental database migrations; their detailed explanation belongs in DATABASE.md.
• Logs and diagnostics must avoid tokens, authorization codes, credentials, personal fields, confidential file metadata, and raw provider payloads. Return and log only the minimum operational error information.
• Seeds, SQL tests, examples, and exceptional data-loading scripts must not contain production secrets or real credentials. Personal or confidential production data must not become a general repository fixture.

See ARCHITECTURE.md for security boundaries and DATABASE.md for current persistence controls and limitations.

Repository Conventions

Only the following conventions are observable in the tracked repository:

• Next.js App Router special files use page.tsx, layout.tsx, loading.tsx, and route.ts. Route groups use parentheses, as in app/(app)/.
• Multiword URL segments use kebab-case in the current application. Component filenames are predominantly lowercase kebab-case, but older mixed-case filenames remain; do not infer a fully enforced filename linter.
• React component exports use PascalCase. Client components that require browser behavior declare "use client".
• TypeScript strict mode is enabled. The @/* alias resolves from the repository root, while files within a focused server module also use relative imports.
• Generic UI primitives follow the configured shadcn/Radix setup under components/ui/ and use lib/utils.ts for class-name composition.
• Server domain files use descriptive suffixes such as .service.ts, .repository.ts, and .types.ts where that pattern is established.
• Auth code is grouped by responsibility using google/, providers/, services/, and storage/ subareas.
• Database migrations use ordered three-digit prefixes and descriptive snake-case names. Seeds and SQL tests also use numeric prefixes within their own areas.
• Generated Markdown schema and project-tree files contain generated-file notices and regeneration commands.
• Canonical documentation uses uppercase filenames for the primary guides and purpose-specific lowercase subdirectories.
• Cortexa dependencies use local file: package references; their implementations are not vendored here.
• The root package exposes application commands plus db:schema and docs:tree. There is no root test command.

These are common or configured patterns, not a license to normalize unrelated files during a focused change.

Generated And Ignored Areas

Do not treat generated, dependency, build, cache, or local-only content as handwritten source:

• Root .next/, node_modules/, out/, and coverage/ are ignored runtime or tool output.
• documentation/node_modules/, documentation/build/, documentation/.docusaurus/, and documentation caches are site dependencies or output.
• .env* files are ignored local configuration and may contain secrets. Never copy their values into source or docs.
• supabase/.temp/ is ignored linked-project or CLI state used by tooling.
• supabase/migrations/ and supabase/seed.sql are ignored generated staging artifacts used by the local Supabase workflow. Canonical migrations and seeds remain under database/.
• docs/repository/project-tree.md, database/schema/*, and the corresponding generated files under docs/database/ must be regenerated rather than hand-edited.
• documentation/docs/ contains synchronized publication copies; update the canonical source and use the sync workflow.
• next-env.d.ts is framework-managed, tsconfig.tsbuildinfo is compiler metadata even though it is tracked, and package lockfiles are package-manager-managed.
• Local assistant/tool metadata and temporary logs are not repository modules even when present in a checkout.

Inactive, Empty, Or Superseded Areas

A directory or artifact is not active merely because it exists in a checkout, generated tree, schema, or older document.

• The local supabase/ directory is an active tooling boundary, not a canonical schema source. Its tracked config.toml configures the local Supabase CLI workflow, while ignored migrations/, seed.sql, and .temp/ content are generated or machine-local staging artifacts. Canonical migrations and seeds remain under database/.
• There is no tracked server/documents/ or components/documents/ module. Database document tables and older documentation do not establish an active application module.
• database/schema.dbml and older seed content describe a superseded model and must not override migrations or the generated schema export.
• lib/supabase-client.ts is tracked but has no current imports; use the runtime-specific lib/supabase/ factories as the established path.
• Empty, deleted, mock-only, sample, or schema-only areas must not be promoted to active responsibilities without current imports, runtime use, or an approved durable decision.

When an area becomes active, add code in the appropriate existing boundary and update this guide only if the responsibility or navigation model changes.

Documentation Corpus Map

README.md

Use README.md for the repository entry point, quick setup, common commands, and introductory context. It is intentionally less authoritative than current code and the responsibility-specific documents.

ARCHITECTURE.md

Use ARCHITECTURE.md for architectural responsibilities, system boundaries, contracts, invariants, security boundaries, and design intent.

REPOSITORY.md

Use this document for organization, navigation, directory responsibilities, code placement, and repository conventions.

repository/project-tree.md

Use repository/project-tree.md to locate current files and directories and to inspect broad checkout structure. It:

• is generated by scripts/generate-project-tree.ps1;
• must not be edited manually;
• is regenerated with npm run docs:tree;
• does not define architecture, domain ownership, activity, or code-placement policy;
• should be regenerated after meaningful tracked structural changes.

DATABASE.md

Use DATABASE.md for persistence architecture, schema organization, data ownership, grants, RLS, migrations, rollback, and data-lifecycle implications.

The generated database schema reference and SQL export provide structural detail. database/data-dictionary.md is manually maintained supporting material and must be verified against current migrations and exports.

ECOSYSTEM.md

Use ECOSYSTEM.md for TUASESOR, Cortexa, external-provider, and any broader product relationships that are actually evidenced; it owns capability and platform-boundary decisions.

references/CORTEXA_PLATFORM.md

Use references/CORTEXA_PLATFORM.md for shared Cortexa platform context, horizontal capability ownership, and integration relationships. Platform context does not make every described module an active TUASESOR dependency.

Documentation Site

Use the documentation/README.md and documentation/ source for Docusaurus development and publication. Selected files under documentation/docs/ mirror the root README and docs/ sources through scripts/sync-docusaurus-docs.ps1; identify and change the canonical source before editing any mirrored content.

Guidance For Developers And AI Agents

Contributors and AI agents should:

1. Inspect tracked structure, current imports, and runtime implementation before deciding placement.
2. Use this document for repository organization and code placement.
3. Use repository/project-tree.md for navigation only, and verify entries against tracked state.
4. Use ARCHITECTURE.md for responsibilities, dependency direction, contracts, and security boundaries.
5. Read DATABASE.md and current migrations before changing persistence, grants, RLS, rollback, or schema exports.
6. Read ECOSYSTEM.md before moving responsibility between TUASESOR and Cortexa or adding a platform dependency.
7. Preserve browser/server separation and use the runtime-specific Supabase helper.
8. Preserve the distinction among authenticated identity, TUASESOR profile, client-selected workspace context, authorized workspace membership, and provider account.
9. Keep credentials, privileged persistence, and authorization-sensitive logic out of UI components.
10. Prefer existing route, component, server, database, documentation, and script areas over a new top-level directory.
11. Follow existing naming and placement patterns only where they are established; request an explicit design decision where no convention exists.
12. Regenerate the project tree after meaningful tracked structural changes instead of editing it.
13. Update canonical documentation first, then refresh publication copies through the established synchronization workflow when those copies are in scope.
14. Distinguish tracked source from generated output, synchronized copies, dependencies, build output, ignored secrets, and local-only state.
15. Do not document empty, obsolete, deleted, mock-only, or schema-only areas as active modules.

Keeping This Guide Current

Update this guide when a durable change alters a top-level area, module responsibility, package boundary, code-placement rule, database artifact workflow, documentation source/publication boundary, or generated-navigation workflow. Routine implementation inside an established area does not require a repository-guide rewrite.