Skip to navigation
Start here

System architecture

View as Markdown

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

Component responsibilities

ComponentResponsibilityData or boundary
Browser appRenders 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 serviceOwns API authentication, firm resolution, role checks, feature orchestration, and signed storage operations.Persists product records and coordinates configured integrations.
PostgreSQLStores users, firms, memberships, file metadata, reminders, vault ciphertext, and other product records.Does not store uploaded file bytes.
Google Cloud StorageStores uploaded file objects and serves uploads or reads through signed URLs.Requires the deployment’s storage credentials and bucket configuration.
Optional servicesCloud 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 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 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.
  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 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 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/.