TUASESOR Web

TUASESOR Web is the SaaS application and directly owned backend for workspace-oriented business workflows used by small and medium-sized organizations and the professionals who support them.

Overview

This repository contains the TUASESOR browser product, its server-side APIs and orchestration, the tuasesor Supabase data model and security controls, and the canonical technical documentation. The product may handle financial, accounting, labor-related, contractual, client, beneficiary, document, and other confidential business information.

TUASESOR owns the product experience, application profiles and admission rules, product authorization decisions, and operational data model. It uses Supabase for authentication and persistence, consumes locally referenced Cortexa packages for reusable OAuth and Google Drive capabilities, and treats external providers such as Google as authoritative for their resources.

Current Scope

• Application access: Google-backed sign-in through Supabase Auth, server-validated sessions, and normal page-entry checks for an existing TUASESOR profile with an email and active status.
• Workspace-oriented application shell: authenticated navigation and workspace context are active. WorkspaceProvider loads the signed-in profile's available workspaces through a TUASESOR API backed by self-readable memberships and membership-scoped workspace reads. The selected workspace remains browser-held request context rather than authorization proof, and no product workflow currently administers workspaces or memberships.
• Expense reports (rendiciones): authenticated, workspace-scoped listing, detail, initial draft creation, catalog reads, item totals, and secure expense-item creation, update, and deletion are connected through the UI, application APIs, services, repositories, Supabase, and database controls. owner, admin, and member may modify items only while the parent report remains draft; viewer and client remain read-only. Submission, review, approval, rejection, reimbursement, cancellation, document handling, and later lifecycle operations remain incomplete.
• Google Drive and My Space: an authenticated profile can separately authorize read-only Drive access and browse file and folder metadata live. My Space is profile-scoped rather than workspace-scoped, and the current flow does not copy Drive resources into TUASESOR document tables.
• Repository documentation: canonical architecture, repository, database, and ecosystem guides; generated schema and project-tree references; and a separate Docusaurus publication toolchain.

Client management, tasks, calendar, history, control-tower data, automation, document processing, and several database surfaces are mock, preview, closed, transitional, or inactive. Their presence must not be interpreted as an implemented product workflow.

Technology Overview

• Next.js App Router, React, and TypeScript
• Tailwind CSS with Radix/shadcn UI primitives
• Supabase Auth, PostgreSQL/PostgREST, and row-level security (RLS)
• Local Cortexa auth and Google Drive connector packages
• Docusaurus for the separate documentation site

Prerequisites

• Node.js and npm. The root application does not declare a Node.js version. The documentation package requires Node.js 20 or later.
• Local Cortexa packages. Before installing, make the three file: dependencies declared in package.json available at their expected relative paths; their source is not included in this repository.
• Supabase access. Local application use requires a configured Supabase project, the current tuasesor schema, Google sign-in configured for Supabase Auth, and the tracked supabase/config.toml used by the local CLI workflow. Canonical migrations and seeds remain under database/; generated supabase/migrations/ and supabase/seed.sql staging artifacts must not be edited manually.
• Google OAuth access. My Space requires a separate Google OAuth client configured for the application's read-only Drive connection.
• PowerShell. The schema export and project-tree commands use Windows PowerShell scripts. Schema export also requires Docker and linked Supabase project metadata.

Local Development

There is no committed environment-file template. Create an ignored .env.local and provide only the values required for the flows you are running.

npm install
npm run dev:fixed

Open http://localhost:3000/login. Use npm run dev instead when an automatically selected development port is preferable.

Environment Configuration

Variable	Exposure	Purpose
NEXT_PUBLIC_SUPABASE_URL	Public	Supabase project URL used by browser, server, and middleware clients.
NEXT_PUBLIC_SUPABASE_ANON_KEY	Public	Public Supabase anonymous key; database grants and RLS remain the authorization boundary.
GOOGLE_CLIENT_ID	Server only	OAuth client identifier for the separate Google Drive connection.
GOOGLE_CLIENT_SECRET	Server only	OAuth client secret for the Google Drive connection.
GOOGLE_REDIRECT_URI	Server only	Google-registered callback URI for the Drive connection.
NEXT_PUBLIC_APP_URL	Public, optional	Redirect base after connecting Google; the callback falls back to the request origin.
GOOGLE_DRIVE_ROOT_FOLDER_ID	Server only, optional	Restricts the initial Drive listing to a configured root folder.

Signing in to TUASESOR and authorizing Google Drive are separate flows. Supabase Auth establishes the TUASESOR identity and session; the later provider authorization grants read-only access to the connected Google account. Never place client secrets, authorization codes, access tokens, refresh tokens, or service-role credentials in public variables, source files, logs, or documentation.

Available Commands

Command	Purpose
npm run dev	Start the Next.js development server.
npm run dev:fixed	Start the development server explicitly on port 3000.
npm run build	Create the production Next.js build.
npm run start	Serve an existing production build.
npm run docs:tree	Regenerate docs/repository/project-tree.md.
npm run db:schema	Export the linked tuasesor schema and refresh generated schema files under database/schema/ and docs/database/; requires PowerShell, Docker, and a linked Supabase project.
npm --prefix documentation run start	Start the Docusaurus documentation site locally.
npm --prefix documentation run typecheck	Type-check the documentation site.
npm --prefix documentation run build	Build the documentation site and check its links.
powershell -ExecutionPolicy Bypass -File scripts/sync-docusaurus-docs.ps1	Copy the canonical README and selected docs/ sources into the Docusaurus publication tree.

Run npm --prefix documentation install once before using the documentation-site commands.

The root package declares no lint or automated test command. The SQL validation asset under database/tests/ is not wired to a root package script.

Repository and Documentation Navigation

• docs/ARCHITECTURE.md: architectural responsibilities, system boundaries, authentication and authorization contracts, invariants, and design intent.
• docs/REPOSITORY.md: repository organization, code placement, conventions, generated areas, and contributor navigation.
• docs/DATABASE.md: persistence ownership, grants, RLS, migrations, tenant-isolation limits, and data-lifecycle implications.
• docs/ECOSYSTEM.md: capability ownership and boundaries among TUASESOR, Cortexa, Supabase, Google, and external systems.
• docs/repository/project-tree.md: generated structural navigation. Do not edit it manually; regenerate it after meaningful structural changes with npm run docs:tree. It does not define architecture or ownership.
• docs/references/CORTEXA_PLATFORM.md: broader Cortexa platform context; platform descriptions do not make a module an active TUASESOR dependency.
• docs/database/schema.md: generated database structure reference.
• docs/database/data-dictionary.md: supporting domain and database terminology.

The Docusaurus application under documentation/ contains publication copies of selected canonical documents. Change the root README or the relevant docs/ source first, then use the synchronization workflow when publication copies are in scope. Published or copied content never overrides current implementation or canonical repository sources.

Security and Data Handling

• Never commit environment files, OAuth credentials, tokens, authorization codes, service credentials, or production identifiers.
• Keep Google OAuth and Drive operations server-side; return only the metadata required by the product.
• Preserve the distinction between authenticated identity, TUASESOR profile, profile-owned integrations, workspace membership, and workspace-owned records.
• Treat client-selected profile, provider-account, resource, and workspace identifiers as request context, not authorization proof.
• Preserve profile ownership and workspace isolation with server-side checks, least-privilege grants, and RLS. Review migrations, grants, policies, and the security of membership data together before changing persisted access.
• Treat filenames, folder structure, provider metadata, logs, financial data, and derived information as potentially personal or confidential.
• Do not persist external or derived data without an explicit product purpose, ownership model, authorization design, and retention/deletion behavior.

The repository documents known authorization and data-lifecycle gaps; it does not establish complete tenant isolation, operational readiness, or legal compliance. Consult the architecture and database guide before changing sensitive flows.

Contributing

• Inspect current implementation, imports, migrations, grants, and policies before changing behavior or describing a capability as active.
• Follow the placement guidance in docs/REPOSITORY.md, and preserve server-only boundaries for provider credentials and sensitive operations.
• Keep profile-owned and workspace-owned data separate, and never rely on UI workspace state as authorization.
• Update the appropriate canonical guide when setup, responsibilities, ownership, persistence, or ecosystem boundaries materially change.
• Regenerate schema and project-tree artifacts with their verified commands; do not edit generated output manually.
• Synchronize Docusaurus copies when canonical documentation changes are intended for publication.
• Run the relevant available build, type-check, schema-validation, or documentation commands before proposing a merge; do not imply coverage from checks the repository does not define.