> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture overview

> How EntityShield portals, Cloudflare Workers, Auth0 authentication, and tenant-scoped Postgres data fit together.

# Architecture overview

EntityShield separates browser experiences by audience while routing application data through one Hono API on Cloudflare Workers.

```mermaid theme={null}
flowchart LR
  Admin[Admin App<br/>entityshield.app]
  Workspace[Workspace Portal<br/>*.portal.entityshield.app]
  Staff[Staff Portal<br/>staff.entityshield.app]
  Governance[Governance Portal<br/>gov.entityshield.app]
  API[Hono API Worker<br/>api.entityshield.app]
  DB[(Postgres with RLS<br/>Azure Postgres)]
  R2[(Cloudflare R2<br/>5 buckets)]
  Queues[Cloudflare Queues<br/>9 consumers]
  Workers[Jobs, Integrations, Chat,<br/>Email Workers]
  Auth0[Auth0<br/>auth.pcnaid.com]
  Stripe[Stripe<br/>Billing + Webhooks]
  AIGW[Cloudflare AI Gateway]
  OpenAI[OpenAI]

  Admin -->|JWT| API
  Workspace -->|JWT| API
  Staff -->|JWT| API
  Governance -->|JWT| API
  Admin -->|PKCE| Auth0
  Workspace -->|PKCE| Auth0
  Staff -->|PKCE| Auth0
  Governance -->|PKCE| Auth0
  Auth0 -.->|Issues JWTs| API
  API -->|Row-Level Security| DB
  API --> Stripe
  API --> R2
  API --> Queues
  Queues --> Workers
  API --> AIGW --> OpenAI
```

## Four browser surfaces

The **Admin App** is the main React SPA served via Cloudflare Pages at `entityshield.app`. It hosts marketing routes (public) and 50+ protected routes for entities, permits, locations, filings, tasks, compliance, calendar, reports, documents, AI assistant, billing, team, settings, portfolio, imports, and webhooks.

The **Workspace Portal** is a module-driven SPA at `*.portal.entityshield.app`. Modules include operations, inbox, social media, reputation, marketing, inventory, helpdesk, drive, reports, support, team, settings, and AI. Module visibility is gated by workspace memberships and per-module enable/disable.

The **Staff Portal** is a Pcnaid-internal SPA at `staff.entityshield.app` used by Pcnaid staff for cross-tenant operations.

The **Governance Portal** is an entity-scoped SPA at `gov.entityshield.app` for governance members. It includes overview, filings, meetings, documents, equity (cap table, financials), members, and AI (coming soon).

## API and authentication

The API Worker mounts public routes (health, webhooks, public workspace branding, public forms, landing page, iCal feeds) before the `/v1/*` JWT authentication middleware. After authentication, the API distinguishes four token audiences:

* **Admin audience** — `/v1/` routes with route-specific permissions
* **Workspace audience** — `/v1/workspace/*` routes scoped by workspace identity
* **Staff audience** — `/v1/staff/*` routes enforcing Pcnaid staff access
* **Governance audience** — `/v1/governance/*` routes scoped by governance membership

Auth0 Actions decorate JWTs with EntityShield-specific claims: `userId`, `customerId`, `role`, and `workspace_memberships`. The API validates these claims against the matching audience and enforces tenant and route-level permissions.

## Data model

The core relational chain is: `customers` → `users` and `entities` → `locations` → optional location-scoped `permits`. Permits and governance filings always reference an entity; permits may also reference a location. The database has 166+ tables under Row-Level Security (RLS), accessed through a dedicated application login role that cannot bypass RLS.

Every request runs inside a tenant-scoped database context, so the application login role can never see or write data outside the tenant it is serving. Governance and system operations use their own scoped database contexts, and public data is served through a narrowly projected read-only context.

## Workers and infrastructure

| Component | Technology | Role |
| - | - | - |
| API | Cloudflare Worker (Hono) | 148 route mounts, 9 queue consumers |
| Jobs | Cloudflare Worker (cron) | Scheduled tasks |
| Integrations | Cloudflare Worker | Third-party HTTP integrations |
| Chat | Cloudflare Worker (Durable Objects) | Real-time chat |
| Email | Cloudflare Worker (Email Routing) | Inbound email → R2 archive |
| AI Agent | Isolated sandbox | Per-entity AI project container |
| Portals | Cloudflare Pages | 4 React SPAs |
| Object Storage | Cloudflare R2 | 5 buckets |
| Database | Azure Postgres with pooled connections | 166+ tables, RLS |
| AI Gateway | Cloudflare AI Gateway | OpenAI BYOK proxy |

## Deployment

* Portals are deployed to Cloudflare Pages from CI on push to `main`.
* Workers are deployed via `wrangler deploy` from CI.
* Wildcard DNS `*.portal.entityshield.app` routes workspace traffic.
* Custom hostnames (Cloudflare for SaaS) support per-entity customer domains on Pro/Firm tiers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.