# Pactuno architecture

**Status:** v204 tenant, identity, and tier enforcement foundation.

Pactuno now has explicit company and personal tenant records. Onboarded work-email domains map to company tenants; known personal email providers and domains not yet onboarded by Global Admin map to private, per-user tenants. Company records store portal names, logo URLs, theme colors, member roles, and tenant-level audit history. See [ADR 0001](adr/0001-two-surfaces-one-project.md).

## Product boundaries

- **Customer Workspace — `/app/`:** authenticated operations for projects, workspaces, team, My Work, milestones, timelines, calendar, Spaces, documents, Quotes/SOWs, reports, analytics, workflows, integrations, and customer views.
- **Global Admin Console — `/admin/`:** authenticated operator tools for company directory, registered users, plans, access/MFA, support routing, demo environments, and global account summaries. It does not load customer project or Space content. The old `/app/admin.html` URL redirects here.
- **Private demo setup — `/app/demo-start.html`:** after email-code sign-in, creates a fictional sample workspace under that visitor's own user identity. Normal customer accounts and the rest of `/app/` remain the product workspace.
- **Public customer demo — `/customer-demo/`:** static fictional data, no account needed, no customer API requests or server writes. Its live-workspace CTA sends a visitor through email-code sign-in and creates a private sample account workspace.

## Request and code organization

| Path | Responsibility |
|---|---|
| `public/index.html` | Public gateway |
| `public/app/*.html` | Customer workspace UI |
| `public/admin/index.html` | Global Admin Console for operator and tenant management |
| `public/customer-demo/index.html` | Static public sample workspace |
| `public/docs/*` | Published product/engineering references |
| `api/*.js` | JSON endpoints |
| `lib/*.js` | Shared server helpers |
| `migrations/*.sql` | Ordered schema changes and database routines |

Hatchable serves the static files directly and executes API handlers in its isolate. Browser pages use same-origin routes and the Hatchable auth client; API handlers use the SDK and parameterized SQL.

## Identity and data

End users use Hatchable email one-time-code sign-in. Customer and admin surfaces share the identity system. Global Admin pages check the Pactuno admin entitlement before showing controls; every admin API independently enforces admin authorization and MFA requirements. A separate URL is a product boundary, never the only security check.

Customer APIs resolve an explicit tenant membership and then apply project ownership or explicit project membership. A user's personal tenant is unique to their account; Gmail users are never grouped into one shared Gmail workspace. Company branding is returned by `/api/tenant` and applied to the customer workspace. Token-based Client Portal links remain separate from authenticated Customer Workspace access.

Global Admin can open a company-wide General Audit with project progress, win/loss and financial totals, overdue milestones/tasks, active risks and issues, company membership, and the combined company/project audit trail. Tenant-level audit events record Global Admin actions that affect that company.

Schema is managed through migrations. Data groups include accounts/profiles/plans/access; workspaces/memberships; projects/memberships; milestones, tasks, risks, requirements, and approvals; Spaces and messages; documents and versions; audit/communication records; notifications, integrations, and portal tokens.

## Failure behavior

- Validate required IDs and allowed enum values before writes.
- Return stable JSON errors and appropriate 4xx status codes for invalid, unauthorized, missing, or conflicting records.
- Report side effects such as email delivery truthfully.
- Preserve account data if a platform identity operation is denied.
- Keep public demo failures independent from signed-in customer APIs.
- Log useful request context without OTPs, session cookies, share tokens, or full document contents.