How the platform actually works

The product is a single-page web application backed by a managed Postgres platform, a serverless edge function layer, object storage and a small fleet of long-running container workers.

Think of it as a city: the browser app is City Hall, the database is the water network under the streets, edge functions are the buildings, and AI orchestration is the brain hovering above it all.

• 201 Postgres tables, 2 views, 270 database functions, 399 migrations.
• 223 Supabase Edge Functions and 181 shared modules.
• 11 storage buckets and 4 container workers.
• 121 routes across 111 pages, serving six personas.

A user signs in through the managed auth service, which issues a session token stored in the browser. The browser Supabase client attaches it to every Auth, PostgREST, RPC, Storage and Edge Function call, and it is verified server-side before any data is returned.

Authorization is layered rather than a single check: token validity, persona/role from a dedicated roles table, case ownership, storage policies, and finally row-level security in the database. A global session guard signs the user out everywhere if a refresh fails or the session ends in another tab.

• Role is read server-side from the profiles record and enforced by row-level security policies.
• Guest access uses scoped, expiring token links instead of accounts.
• Privileged service-role operations only ever run server-side.

Files live in object storage buckets, never in the database. The database stores only metadata, extraction output and review state, all scoped to a case.

• documents — user uploads, evidence, intake CVs.
• case-deliverables — expert and admin outputs, official result files.
• i140, templates, resume-photos and other purpose-built buckets.
• Metadata tables: case_documents, document_extractions, document_field_suggestions, case_deliverables.

The upload is a five-step pipeline. Nothing is trusted until the extraction has been reviewed.

• 1. The workspace picks a case-scoped document category and target bucket.
• 2. The browser uploads the file directly to storage under the case path; storage policies check ownership.
• 3. Metadata is written to case_documents.
• 4. Extraction runs: text and fields are written to document_extractions and proposed in document_field_suggestions.
• 5. Accepted values sync into the application forms and re-run readiness scoring; tasks and flags update automatically.

Three classes of caller reach Postgres, each with a different privilege level.

• The browser client — always as the signed-in user, always subject to row-level security.
• Edge functions — as the user when acting on their behalf, or with the service role for privileged, audited operations.
• Container workers — with their own secret, writing job status and generated artefacts.
• No human connects directly to production for routine work; schema changes ship as reviewed migrations.

AI is orchestration plus retrieval, not a single model call. Short generations run inside edge functions; long generations are handed to dedicated workers so a request never blocks.

Answers are grounded: relevant policy and canonical facts are retrieved from the knowledge index and passed to the model with the case context, and citations come back with the output.

• OpenAI for edge-side generation and section regeneration.
• Anthropic Claude for full petitions, discovery, policy verification.
• Every call is metered in the AI usage ledger with per-user rate limits.

Anything that can take longer than a request goes through the queue: petition generation, business plans, blog drafts, government e-filing.

• Scheduled database jobs call public endpoints for recurring work; those endpoints verify the caller.
• Workers write progress so the UI can show live status and resume after refresh.
• Failures are recorded and retried rather than silently dropped.

Nineteen external services are reached only from the server side, with secrets injected at call time.

• Government/consular: CEAC DS-160, US State Department, Canada IRCC, UK Gov.
• Research: OpenAlex, Crossref, Google Scholar, SerpAPI, Jina Reader.
• Media & delivery: Cloudflare Stream, ElevenLabs, HeyGen, PDFShift, Resend.
• DS-160 e-filing drives a managed headless Chromium session against the consular site from an isolated worker.

The frontend is served from a global CDN with SPA rewrites; the backend is a managed platform with an edge runtime plus container workers for long jobs.

• CI/CD: typecheck, edge function deploy, main health check and visual regression workflows.
• Tests: Vitest + jsdom for the frontend, Deno tests for edge logic, Playwright for visual diffs.
• Secrets are environment-injected; no private key ships in the browser bundle.
• Managed automated backups with point-in-time recovery; forward-only migrations.

Frontend exceptions are captured with release and source maps; user-facing errors carry a reference code support can trace back to the event.

• Scheduled health workflow probes production.
• AI usage ledger surfaces cost and rate-limit pressure per feature.
• Known-failure lanes stop one bad integration from taking down a workspace.