Skip to main content

​
Architecture overview

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

​
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

​
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.