How spurbey/dora works
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: services Services · v1 API v1 · server.js Renderer API · workers Workers
Components 20
Backend
FastAPI system of record, domain logic, persistence, and background workers.
- API v1 · HTTP boundary for auth, trips, places, routes, media, search, exports, and live tracking.
backend/app/api/v1 - Services · Business logic for trips, places, routes, media, search, exports, pushes, and live tracking.
backend/app/services - Models · Canonical persistence layer for trips, places, routes, metadata, media, tracking, exports, and users.
backend/app/models - Workers · Async processing for export jobs and live tracking pipelines.
backend/app/workers - Migrations · Alembic/PostGIS database schema history and rollout state.
backend/alembic - Supabase auth · External identity and storage-related integration behind backend endpoints.
docs/apis/supabase.md - Search service · Normalized search signals and retrieval/ranking over spatial and content data.
backend/app/services/search_service.py - Live tracking · 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 · Auth, networking, navigation, storage, sync, media, map, notifications, and theming.
flutter/lib/core - Drift store · Local persistence for trips, routes, places, media, tracking, and sync tasks.
flutter/lib/core/storage - Sync engine · Entity sync and tracking sync workers bridging local state with backend APIs.
flutter/lib/core/sync - Create editor · Trip/place/route editing, map interactions, timeline, compiled projection, and live capture UI.
flutter/lib/features/create - Live capture · Dedicated live capture workflow spanning event resolution, map control, and capture state.
flutter/lib/features/live_capture - Export UI · Export studio, share preview, and export job management in the mobile client.
flutter/lib/features/export - Dora API · 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 · 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 · Bounded Node service contract that receives structured export jobs and returns render outputs.
video-renderer/src/server.js - Render engine · 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 · IAM and S3 lifecycle templates isolating cloud render operations.
infra/remotion - Scrapers · Place/review collection and extraction utilities supporting enrichment and experimentation.
scraper_gmaps
Connections 20
- 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.