# spurbey/dora architecture

> Architecture diagram of the GitHub repository spurbey/dora, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spurbey/dora
- Repository: https://github.com/spurbey/dora

## Overview

1. **Overall shape**
   - Dora is a monorepo with four runtime surfaces: a FastAPI backend, an offline-first Flutter app, a legacy React web client, and a Node/Remotion video renderer. Supporting pieces include deployment/IAM templates and scraper utilities.

2. **Backend is the system of record**
   - `backend/` owns the authoritative API, domain models, and database schema. It uses FastAPI, SQLAlchemy-style models/schemas, Alembic migrations, PostgreSQL with PostGIS, and integrates with Supabase for auth/storage-related concerns.
   - The backend is organized around `api/v1`, `services`, `models`, `schemas`, and `workers`, which cleanly separates HTTP boundaries from business logic and background processing.

3. **Core backend domains**
   - The main backend subsystems are trips, places, routes, components, metadata, media, search, exports, live tracking, and user/auth.
   - PostGIS matters architecturally because trips/routes/places are spatially queried and indexed, not just CRUD entities.

4. **Client-server contract boundary**
   - The Flutter app consumes the backend through a generated OpenAPI client package (`flutter/packages/dora_api`), which makes the backend API contract a hard boundary.
   - The React frontend uses its own service layer and types, but appears secondary/parallel rather than the primary product surface.

5. **Flutter app is offline-first**
   - `flutter/` is built around local persistence and synchronization: Drift database tables/DAOs, sync workers, queued tasks, and repository layers.
   - This means the mobile client can edit/create content locally, then reconcile with the backend through dedicated sync flows rather than requiring every action to be online.

6. **Flutter feature partitioning**
   - Flutter is split into feature modules such as auth, create/editor, feed, live capture, export, profile, and trips.
   - Shared core services handle auth tokens, network retry/auth interception, map adapters, media uploads, notifications, storage, and navigation; the UI layer sits on top of these cross-cutting foundations.

7. **Map, media, and live capture are first-class workflows**
   - The mobile app integrates mapping, geocoding, directions, location permissions, media compression/upload, and push/deep-link bootstrapping.
   - Live tracking/capture is a distinct subsystem spanning UI, local capture state, sync primitives, and backend APIs, indicating a real-time event pipeline rather than a simple form submission flow.

8. **Export pipeline is a separate backend/renderer system**
   - Exports are not rendered inside the API server. The backend creates and tracks export jobs, while a background worker coordinates with `video-renderer/`.
   - The renderer is a Node service built on Remotion, with both local/server and Lambda-oriented paths. It produces video/thumbnail assets and returns job outputs back through backend job state.

9. **Renderer is a bounded service**
   - `video-renderer/` has its own API contract, tests, and render planning logic. It consumes structured render data from the backend and is responsible only for visual composition/render execution.
   - The `infra/remotion/` folder contains IAM and S3 lifecycle templates, showing that cloud rendering is operationally isolated from the core application.

10. **Search and external providers**
   - Search is a backend service backed by normalized signals and indexed data, with Flutter and possibly web clients consuming it through API endpoints.
   - Place and route enrichment also involve external providers, notably Foursquare and Mapbox, but those are adapters behind backend/mobile service boundaries rather than direct UI dependencies.

11. **Frontend web client is parallel, not primary**
   - `frontend/` is a Vite + React application with its own auth, editor, map, media, trip, and place components, plus a local store/hooks architecture.
   - It likely targets the same backend API and domain model, but the repository positioning and docs indicate Flutter is the primary active client.

12. **Operational and delivery boundaries**
   - GitHub Actions covers backend CI, Flutter CI/builds, and Railway deployment.
   - The repo also includes extensive phase docs, architecture notes, and external policy pages, suggesting the architecture is shaped by staged product phases and release-readiness constraints rather than a single greenfield codebase.

13. **Ancillary scraping/tooling**
   - `scraper_gmaps/`, `scraper_lean/`, and `scraper_test/` are separate data collection and experimentation tools, likely used to gather place/review data and validate extraction pipelines.
   - They are not core product runtime components, but they support the data ingestion ecosystem around places/search.

14. **How data flows end-to-end**
   - User identity comes from Supabase-backed auth, then clients call the backend API with bearer tokens.
   - The backend persists canonical data in Postgres/PostGIS, coordinates media/storage and push-related side effects, and spawns background jobs for exports or live-tracking processing.
   - Flutter keeps local state in Drift, syncs to the backend, and uses the generated API package to stay aligned with the server contract.

Main entry points: [`backend/app/services`](https://github.com/spurbey/dora/tree/main/backend/app/services) (Services), [`backend/app/api/v1`](https://github.com/spurbey/dora/tree/main/backend/app/api/v1) (API v1), [`video-renderer/src/server.js`](https://github.com/spurbey/dora/blob/main/video-renderer/src/server.js) (Renderer API), [`backend/app/workers`](https://github.com/spurbey/dora/tree/main/backend/app/workers) (Workers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_api["API v1<br/>FastAPI routes"]
  node_backend_services["Services"]
  node_backend_models[("Models")]
  node_backend_workers["Workers<br/>background jobs"]
  node_backend_migrations["Migrations<br/>schema evolution"]
  node_backend_supabase["Supabase auth<br/>auth/storage boundary<br/>[supabase.md]"]
  node_backend_search["Search service<br/>indexing logic<br/>[search_service.py]"]
  node_backend_live["Live tracking<br/>event pipeline"]
end

subgraph group_flutter["Flutter app"]
  node_flutter_core["Core platform<br/>client foundations"]
  node_flutter_storage[("Drift store<br/>offline database")]
  node_flutter_sync["Sync engine<br/>reconciliation"]
  node_flutter_create["Create editor<br/>feature module"]
  node_flutter_live["Live capture<br/>feature module"]
  node_flutter_export["Export UI<br/>feature module"]
  node_flutter_api_pkg["Dora API<br/>generated client"]
end

subgraph group_frontend["Web client"]
  node_frontend_app["React app<br/>Vite React client"]
end

subgraph group_renderer["Video renderer"]
  node_renderer_api["Renderer API<br/>render contract<br/>[server.js]"]
  node_renderer_gl["Render engine<br/>Remotion pipeline"]
end

subgraph group_ops["Ops & tooling"]
  node_infra_remotion["Remotion infra<br/>cloud templates"]
  node_scrapers["Scrapers<br/>ingestion tools"]
end

node_backend_api -->|"delegates"| node_backend_services
node_backend_services -->|"persists"| node_backend_models
node_backend_services -.->|"evolves schema"| node_backend_migrations
node_backend_services -.->|"auths"| node_backend_supabase
node_backend_services -->|"indexes"| node_backend_search
node_backend_services -->|"coordinates"| node_backend_live
node_backend_workers -->|"dispatches jobs"| node_renderer_api
node_renderer_api -->|"executes"| node_renderer_gl
node_backend_workers -->|"updates job state"| node_backend_models
node_flutter_api_pkg -->|"generated from"| node_backend_api
node_flutter_core -->|"uses"| node_flutter_storage
node_flutter_core -->|"drives"| node_flutter_sync
node_flutter_create -->|"reads/writes"| node_flutter_storage
node_flutter_create -->|"calls"| node_flutter_api_pkg
node_flutter_live -->|"streams"| node_flutter_sync
node_flutter_live -->|"submits events"| node_backend_live
node_flutter_export -->|"requests jobs"| node_backend_api
node_frontend_app -->|"calls"| node_backend_api
node_infra_remotion -.->|"provisions"| node_renderer_api
node_scrapers -.->|"feeds data"| node_backend_services

click node_backend_api "https://github.com/spurbey/dora/tree/main/backend/app/api/v1"
click node_backend_services "https://github.com/spurbey/dora/tree/main/backend/app/services"
click node_backend_models "https://github.com/spurbey/dora/tree/main/backend/app/models"
click node_backend_workers "https://github.com/spurbey/dora/tree/main/backend/app/workers"
click node_backend_migrations "https://github.com/spurbey/dora/tree/main/backend/alembic"
click node_backend_supabase "https://github.com/spurbey/dora/blob/main/docs/apis/supabase.md"
click node_backend_search "https://github.com/spurbey/dora/blob/main/backend/app/services/search_service.py"
click node_backend_live "https://github.com/spurbey/dora/blob/main/backend/app/services/live_tracking_service.py"
click node_flutter_core "https://github.com/spurbey/dora/tree/main/flutter/lib/core"
click node_flutter_storage "https://github.com/spurbey/dora/tree/main/flutter/lib/core/storage"
click node_flutter_sync "https://github.com/spurbey/dora/tree/main/flutter/lib/core/sync"
click node_flutter_create "https://github.com/spurbey/dora/tree/main/flutter/lib/features/create"
click node_flutter_live "https://github.com/spurbey/dora/tree/main/flutter/lib/features/live_capture"
click node_flutter_export "https://github.com/spurbey/dora/tree/main/flutter/lib/features/export"
click node_flutter_api_pkg "https://github.com/spurbey/dora/tree/main/flutter/packages/dora_api"
click node_frontend_app "https://github.com/spurbey/dora/tree/main/frontend/src"
click node_renderer_api "https://github.com/spurbey/dora/blob/main/video-renderer/src/server.js"
click node_renderer_gl "https://github.com/spurbey/dora/tree/main/video-renderer/src/remotion/gl"
click node_infra_remotion "https://github.com/spurbey/dora/tree/main/infra/remotion"
click node_scrapers "https://github.com/spurbey/dora/tree/main/scraper_gmaps"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend_api,node_backend_services,node_backend_models,node_backend_workers,node_backend_migrations,node_backend_supabase,node_backend_search,node_backend_live toneBlue
class node_flutter_core,node_flutter_storage,node_flutter_sync,node_flutter_create,node_flutter_live,node_flutter_export,node_flutter_api_pkg toneAmber
class node_frontend_app toneMint
class node_renderer_api,node_renderer_gl toneRose
class node_infra_remotion,node_scrapers toneIndigo
```

## Components

### Backend

FastAPI system of record, domain logic, persistence, and background workers.

- [API v1](https://github.com/spurbey/dora/tree/main/backend/app/api/v1): FastAPI routes · HTTP boundary for auth, trips, places, routes, media, search, exports, and live tracking. · `backend/app/api/v1`
- [Services](https://github.com/spurbey/dora/tree/main/backend/app/services): domain services · Business logic for trips, places, routes, media, search, exports, pushes, and live tracking. · `backend/app/services`
- [Models](https://github.com/spurbey/dora/tree/main/backend/app/models): domain models · Canonical persistence layer for trips, places, routes, metadata, media, tracking, exports, and users. · `backend/app/models`
- [Workers](https://github.com/spurbey/dora/tree/main/backend/app/workers): background jobs · Async processing for export jobs and live tracking pipelines. · `backend/app/workers`
- [Migrations](https://github.com/spurbey/dora/tree/main/backend/alembic): schema evolution · Alembic/PostGIS database schema history and rollout state. · `backend/alembic`
- [Supabase auth](https://github.com/spurbey/dora/blob/main/docs/apis/supabase.md): auth/storage boundary · External identity and storage-related integration behind backend endpoints. · `docs/apis/supabase.md`
- [Search service](https://github.com/spurbey/dora/blob/main/backend/app/services/search_service.py): indexing logic · Normalized search signals and retrieval/ranking over spatial and content data. · `backend/app/services/search_service.py`
- [Live tracking](https://github.com/spurbey/dora/blob/main/backend/app/services/live_tracking_service.py): event pipeline · Tracking sessions, events, notifications, and live capture processing. · `backend/app/services/live_tracking_service.py`

### Flutter app

Offline-first mobile/client runtime with local sync and generated API contract.

- [Core platform](https://github.com/spurbey/dora/tree/main/flutter/lib/core): client foundations · Auth, networking, navigation, storage, sync, media, map, notifications, and theming. · `flutter/lib/core`
- [Drift store](https://github.com/spurbey/dora/tree/main/flutter/lib/core/storage): offline database · Local persistence for trips, routes, places, media, tracking, and sync tasks. · `flutter/lib/core/storage`
- [Sync engine](https://github.com/spurbey/dora/tree/main/flutter/lib/core/sync): reconciliation · Entity sync and tracking sync workers bridging local state with backend APIs. · `flutter/lib/core/sync`
- [Create editor](https://github.com/spurbey/dora/tree/main/flutter/lib/features/create): feature module · Trip/place/route editing, map interactions, timeline, compiled projection, and live capture UI. · `flutter/lib/features/create`
- [Live capture](https://github.com/spurbey/dora/tree/main/flutter/lib/features/live_capture): feature module · Dedicated live capture workflow spanning event resolution, map control, and capture state. · `flutter/lib/features/live_capture`
- [Export UI](https://github.com/spurbey/dora/tree/main/flutter/lib/features/export): feature module · Export studio, share preview, and export job management in the mobile client. · `flutter/lib/features/export`
- [Dora API](https://github.com/spurbey/dora/tree/main/flutter/packages/dora_api): generated client · Generated OpenAPI client contract consumed by Flutter as a hard API boundary. · `flutter/packages/dora_api`

### Web client

Legacy React client with its own UI, store, and service layer.

- [React app](https://github.com/spurbey/dora/tree/main/frontend/src): Vite React client · Legacy web surface with its own auth, editor, map, media, trip, and place UI. · `frontend/src`

### Video renderer

Node/Remotion export runtime and render planning service.

- [Renderer API](https://github.com/spurbey/dora/blob/main/video-renderer/src/server.js): render contract · Bounded Node service contract that receives structured export jobs and returns render outputs. · `video-renderer/src/server.js`
- [Render engine](https://github.com/spurbey/dora/tree/main/video-renderer/src/remotion/gl): Remotion pipeline · Composition, snapshot normalization, camera planning, and render-plan execution. · `video-renderer/src/remotion/gl`

### Ops & tooling

Deployment templates, CI, and scraper utilities around the product runtime.

- [Remotion infra](https://github.com/spurbey/dora/tree/main/infra/remotion): cloud templates · IAM and S3 lifecycle templates isolating cloud render operations. · `infra/remotion`
- [Scrapers](https://github.com/spurbey/dora/tree/main/scraper_gmaps): ingestion tools · Place/review collection and extraction utilities supporting enrichment and experimentation. · `scraper_gmaps`

## Connections

- API v1 → Services: delegates · HTTP handlers call into domain services for business operations.
- Services → Models: persists · Services read and write canonical domain records.
- Services → Migrations: evolves schema · Services rely on the PostGIS-backed schema defined by migrations.
- Services → Supabase auth: auths · Backend resolves identity and related storage concerns through Supabase.
- Services → Search service: indexes · Search signals are normalized and queried from backend services.
- Services → Live tracking: coordinates · Live capture and tracking flows are orchestrated by backend services.
- Workers → Renderer API: dispatches jobs · Export worker sends render work to the renderer service.
- Renderer API → Render engine: executes · Renderer API hands structured jobs into Remotion composition/render logic.
- Workers → Models: updates job state · Workers persist export and tracking processing results.
- Dora API → API v1: generated from · Mobile client contract is generated from the backend OpenAPI surface.
- Core platform → Drift store: uses · Offline-first app stores local entities and sync metadata in Drift.
- Core platform → Sync engine: drives · Core platform bootstraps entity and tracking synchronization.
- Create editor → Drift store: reads/writes · Editor features operate on local state before sync.
- Create editor → Dora API: calls · Create/editor workflows use the generated backend client.
- Live capture → Sync engine: streams · Live capture events and receipts flow through sync primitives.
- Live capture → Live tracking: submits events · Live capture interacts with backend tracking endpoints.
- Export UI → API v1: requests jobs · Export UI creates and tracks backend export jobs.
- React app → API v1: calls · Web client talks to the same backend API surface.
- Remotion infra → Renderer API: provisions · Cloud templates support bounded renderer deployment/runtime.
- Scrapers → Services: feeds data · Scraper outputs support place enrichment and search inputs.
