Developer Guide Overview

Navaid is a multi-tenant readiness platform for companies preparing to enter the UK market. It combines structured advisory conversations, a shared company-level maturity model, recommended tasks, company knowledge, competitor research, multiplayer sessions, and optional live voice.

This guide describes the repository as it exists on main. Counts in this page refer to checked-in source, not to the state of any remote deployment:

• 26 Supabase Edge Function source directories
• 31 PostgreSQL tables created by 72 ordered migrations
• a React 19 single-page application under frontend/
• a separate long-running LiveKit Agents worker under agent/
• this Docusaurus documentation site under docs/

Remote Supabase, Cloudflare Pages, LiveKit, R2, Sentry, Resend, and Google Gemini configuration must be verified in their respective control planes.

What the platform does

The principal user journeys are:

1. An invited or invite-code-authorised user signs in with a six-digit email OTP.
2. The user creates a company or accepts membership of an existing company.
3. A conversation gathers evidence about the company's UK-market readiness.
4. Navaid converts evidence into confidence-weighted signals across 15 maturity dimensions in three rings.
5. The shared company maturity state, company facts, tasks, and session transcript are persisted.
6. Completion produces a narrative summary, constraints, role-specific next steps, warning flags, tasks, and a maturity snapshot.
7. Administrators manage companies, prompts, feature flags, budgets, partners, invitations, feedback, and the optional runtime accent theme.

Additional surfaces include:

• Aida, an in-app assistant with a client-side tool registry
• multiplayer text sessions using Supabase Realtime
• LiveKit group voice using a separately deployed agent worker
• competitor analysis and Prospect Radar grounded research
• optional company-document retention in Cloudflare R2
• public, revocable session-summary shares
• a remote Model Context Protocol server protected by Supabase OAuth 2.1
• a guided demo built around an isolated, short-lived workspace

Technology baseline

Layer	Current checked-in technology
Web application	React 19.2, TypeScript 6.0, Vite 8
Styling	Tailwind CSS 4 through @tailwindcss/vite; CSS theme tokens in frontend/src/index.css
Routing	React Router 7
Client state	Zustand 5
Server-state cache	TanStack React Query 5
Backend	Supabase Postgres 17, Auth, Realtime, Storage, Edge Functions
Edge runtime	Deno 2
AI	Google Gen AI SDK and Gemini text, Live, and TTS models
Group voice	LiveKit Cloud plus the Node worker in agent/
Object storage	Optional Cloudflare R2
Email	Supabase Auth SMTP for OTP; Resend Edge Functions for branded application mail
Observability	Sentry browser SDK, tracing, replay, release source maps
Tests	Vitest, Testing Library, Playwright
DAST	StackHawk HawkScan against local synthetic Supabase
Documentation	Docusaurus 3.10
Frontend hosting	Cloudflare Pages

Use Node.js 20 or later. Frontend dependency-lock changes must be generated and checked with npm 10, matching the Cloudflare builder. See Getting Started.

Repository map

brenter/
├── frontend/
│   ├── src/
│   │   ├── aida/                 # Aida widget, tools, page interaction
│   │   ├── components/           # Shared UI, chat, admin, voice, knowledge
│   │   ├── demo/                 # Guided-demo orchestration and narration
│   │   ├── hooks/                # Auth, feature flags, voice, multiplayer
│   │   ├── i18n/                 # Resources, types, locale transforms
│   │   ├── pages/                # Route-level screens
│   │   ├── services/api/         # Domain-oriented API helpers
│   │   ├── stores/               # Zustand stores
│   │   ├── test/                 # Vitest suites and setup
│   │   ├── types/                # Domain types and maturity catalogue
│   │   └── utils/                # Permissions, formatting, extraction
│   ├── e2e/                      # Playwright setup, fixtures, specifications
│   ├── public/                   # Static assets, security headers, redirects
│   ├── package.json
│   └── vite.config.ts
├── supabase/
│   ├── functions/
│   │   ├── _shared/              # HTTP, authz, budgets, locale, maturity
│   │   └── <slug>/index.ts       # 26 checked-in function entry points
│   ├── migrations/               # 72 ordered SQL migrations
│   └── config.toml               # Local/Git-ignored; create and verify per workstation
├── agent/
│   ├── src/agent.ts              # Long-running LiveKit/Gemini worker
│   ├── .env.example
│   └── README.md
├── docs/
│   ├── docs/developer-guide/     # This guide
│   ├── docs/user-guide/
│   └── docusaurus.config.ts
├── .stackhawk/                   # Saved local PostgREST scan definition
├── scripts/                      # Local setup, seed, scan, and helper scripts
├── stackhawk.yml
└── LOCAL_DAST_RUNBOOK.md

There is no tailwind.config.ts: Tailwind v4 is configured through the Vite plugin and CSS-first @theme declarations.

Architectural boundaries

The most important boundaries are:

• The browser may use the Supabase anon key. It must never receive the service-role key.
• RLS is authoritative for direct browser-to-Supabase access.
• Edge Functions use a service-role client for cross-table work, so every function must verify identity and bind client-supplied identifiers to an authorised company, session, invitation, or document.
• All checked-in functions use verify_jwt = false at the gateway and perform authentication in application code. This is required because the gateway rejects the project's ES256 tokens and because WebSocket/MCP discovery endpoints need custom challenge behaviour.
• The LiveKit agent is not an Edge Function. It is a persistent process that holds room and Gemini Live connections and therefore has its own secret boundary.
• Company maturity is shared at company_profiles.maturity_state; sessions retain their own snapshots for attribution and progression.
• Application emails derive links from the APP_URL function secret, never from request-provided origins.
• Every Gemini-spending path records audit usage and updates the atomic monthly roll-up used for budget enforcement.

See Architecture, Security and Privacy, and AI and Token Accounting.

Tenancy and roles

Users can have multiple active company memberships. The currently selected company is client state, not an authorization boundary.

Scope	Role	Effective capability
Platform	is_system_admin = true	Cross-company administration and feature configuration
Company	company_admin	Full company administration
Company	company_consultant	Deliberately admin-equivalent; used for consultant-specific experiences
Company	company_manager	Company-wide session visibility and task management
Company	company_user	Own sessions and member-scoped company data

Only memberships with status = 'active' confer access. Authorization helpers must keep company_admin and company_consultant in lockstep.

Data domains

The 31 public tables are grouped into:

• identity and tenancy
• sessions, messages, shares, participants, and snapshots
• maturity tasks and company profiles
• token usage and budget alerts
• partners and referrals
• prompts, configuration, and admin audit
• feedback, early access, invitation codes, and signup reservations
• competitor analyses
• company-document metadata and storage accounting
• rate-limit and idempotency ledgers

The migration chain, not an old CREATE TABLE excerpt, is the source of truth. See Database Schema.

Checked-in Edge Functions

The 26 function source directories are:

aida                         aida-live
chat                         chat-live
chat-multi                   competitor-analysis
delete-account               demo
documents                    early-access
gemini-tts                   generate-summary
invite-codes                 lead-hunt
livekit-session-control      livekit-token
mcp                          notify-feedback
notify-session-add           prompt-test
send-invite                  shared-session
structure-feedback           synthesise-company-info
tasks                        update-company-facts

A local, Git-ignored supabase/config.toml may contain declarations for future function names without source directories. Do not count local placeholders as implemented functions. See Edge Functions.

Navaid design language

The application and documentation use the Navaid 2026 palette:

• Deep Teal #2C615F
• Light Teal #7DA19C
• Cream #FCF4DE
• Work Sans

The application keeps legacy coral and navy token names as compatibility aliases, but they now map into the Navaid teal family. The System Admin theme control changes the generated brand-teal accent scale only; fixed primary action tokens remain Navaid Deep Teal. See Theming.

How to use this guide

• Start with Getting Started.
• Use Frontend, Edge Functions, and Database Schema while implementing features.
• Read Authentication and Security and Privacy before changing access control.
• Read The Maturity Engine and AI and Token Accounting before changing AI prompts or pipelines.
• Use Testing and Accessibility for verification and Deployment plus Operations Runbooks for release work.