> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.whizcozy.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.whizcozy.com/_mcp/server.

# System architecture

> How the WhizBoard browser app, API, storage, and external services fit together.

WhizBoard is split across a browser application and a FastAPI service. The browser owns the interactive workspace and sends authenticated requests to the API. The API resolves firm membership, applies server-side role checks, coordinates database records, and connects to storage or configured providers.

![System context diagram showing the browser app, FastAPI service, PostgreSQL, Google Cloud Storage, and optional external services](/_fern-files/whizboard.docs.buildwithfern.com/03afb8800b1148339ffd44a94cde05dd5faa220caa50ecdfe10dd1300e3689a3/docs/assets/diagrams/system-context.svg)

## Component responsibilities

| Component            | Responsibility                                                                                               | Data or boundary                                                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Browser app          | Renders firm and client workspaces, keeps the signed-in session, and calls the API.                          | Sends ordinary REST requests and opens an SSE stream for AI chat. Resumable file bytes go directly from the browser to Google Cloud Storage. |
| FastAPI service      | Owns API authentication, firm resolution, role checks, feature orchestration, and signed storage operations. | Persists product records and coordinates configured integrations.                                                                            |
| PostgreSQL           | Stores users, firms, memberships, file metadata, reminders, vault ciphertext, and other product records.     | Does not store uploaded file bytes.                                                                                                          |
| Google Cloud Storage | Stores uploaded file objects and serves uploads or reads through signed URLs.                                | Requires the deployment's storage credentials and bucket configuration.                                                                      |
| Optional services    | Cloud Tasks or another task handoff, an AI provider, a reminder scheduler, and Resend email.                 | Their credentials, schedules, and production readiness are deployment-specific.                                                              |

## Request and data paths

1. A person opens a firm route in the browser and signs in. The API identifies the user from the JWT, resolves the firm from the route slug, then checks the user's firm membership and role. The [identity guide](/identity-and-firm-access) covers that boundary.
2. For a file upload, the API creates and tracks file metadata while the browser transfers file bytes directly to object storage. The [upload guide](/files-and-uploads) shows the lifecycle.
3. AI chat streams events over Server-Sent Events (SSE). File extraction and indexing use a separate, optional task path described in [File AI and chat](/file-ai-and-chat).
4. Reminder records are stored by the API. A configured external scheduler must call the dispatch endpoint for due reminders to produce notifications or email. The [Notify and reminders guide](/notify-and-reminders) explains that dispatch boundary.

## What the repositories establish

The source repositories establish application code and configuration defaults. They do not establish which cloud credentials, AI provider, task queue, or reminder schedule are active in a deployed environment. Treat those as deployment requirements until the deployment configuration confirms them. The generated [API reference](/api-reference) can also lag code changes because it is synced from the production OpenAPI document.

## Code map

* UI shell and route composition: WhizBoard UI, `src/components/firm/firm-shell.tsx` and `src/routes/`.
* API startup and router registration: backend, `src/main.py`.
* Authentication and firm context: backend, `src/core/dependencies.py`, `src/routers/firms.py`.
* Feature behavior: backend routers, controllers, and services under `src/routers/`, `src/controllers/`, and `src/services/`.