How metal-code/orbit works
1. Repository shape
- This repo is a two-app monorepo: a TanStack Start / React frontend at the root frontend/ and a FastAPI backend in backend/.
- The two halves are independently deployable and communicate only over HTTP/JSON, with JWT bearer auth for protected requests.
2. System boundary
- The frontend owns presentation, routing, optimistic interaction, and client-side token storage.
- The backend owns all business rules, persistence, auth verification, file-upload signing, and AI/RAG logic.
- External services are part of the backend’s runtime boundary: SQLite, AWS S3, ChromaDB, Redis (Upstash), Mistral AI, and Gmail SMTP.
3. Frontend surface and routing
- The frontend is a file-routed SSR app using TanStack Router/TanStack Start.
- Route groups map cleanly to product surfaces: public marketing (/, /about, /report), auth (/login, /register, /verify-otp, /join), and authenticated app views (/dashboard, /projects/:id/timeline).
- src/routes/__root.tsx is the top-level shell; routeTree.gen.ts is generated routing metadata.
4. Frontend data and API layer
- src/lib/api.ts centralizes all backend calls through one Axios instance.
- It injects Authorization: Bearer <token> from localStorage["orbit_token"] on protected requests, and handles 401 by clearing auth state and redirecting to login.
- TanStack Query is wired through src/router.tsx so routes and components can prefetch and hydrate backend data consistently.
5. Frontend feature composition
- The dashboard and timeline are assembled from feature components in src/components/.
- Key UI boundaries are: org/project management modals, timeline entry creation and inspection, and the AI chat panel.
- The landing page includes a Remotion-driven hero asset (frontend/remotion/) which is separate from the main app runtime.
6. Backend entrypoint and layering
- backend/main.py is the ASGI app entrypoint.
- The backend follows a clear router → service → model pattern:
- routers/ expose HTTP endpoints
- services/ implement business logic
- models/ map to database tables
- schemas/ define request/response contracts
- This boundary keeps API concerns thin and pushes real logic into service modules.
7. Persistence model
- Core relational state lives in SQLite via SQLAlchemy.
- Main entities are User, Organization, Project, ProjectMember, TimelineEntry, Link, Attachment, and PendingRegistration.
- The design is multi-tenant: users belong to orgs, projects belong to orgs, and access to a project is mediated by ProjectMember.
- Timeline entries snapshot author name/email so historical records remain stable even if the user changes later.
8. Auth and access control
- Authentication is JWT-based and enforced by dependencies/auth.py using FastAPI Depends.
- Registration is OTP-gated: unverified data stays in PendingRegistration until OTP confirmation creates a real User.
- Authorization is mostly membership-driven:
- org invite codes control org membership
- project invite codes control project access
- project membership is required for timeline and chat access
- Roles are simple and org-level, with owner vs member behavior affecting creation and deletion actions.
9. Timeline and attachment flow
- Timeline entries are the core content object in the product.
- Creating an entry can include nested links and attachments in one request.
- File uploads do not stream through the backend; instead the frontend requests a presigned S3 PUT URL from /upload/presigned-url, uploads directly to S3, then stores the resulting file URL in the timeline entry payload.
- This makes the backend stateless for large files and keeps upload traffic off the API server.
10. AI/RAG subsystem
- The backend has a dedicated rag/ pipeline for project-scoped assistant answers.
- When a timeline entry is created, it is embedded and indexed in ChromaDB along with metadata such as project ID, links, and attachments.
- When a user asks a question, the backend embeds the query, retrieves top matches filtered by the same project, and sends the context to Mistral LLM for the answer.
- The response includes both a natural-language answer and structured sources so the frontend can render clickable references.
11. Chat history subsystem
- Chat history is separate from the RAG store and is kept in Redis via Upstash.
- History is keyed by chat:{project_id}:{user_id} with a 3-day TTL, which makes it temporary and user/project-specific.
- The timeline chatbot hydrates from /projects/{id}/chat/history, appends new turns via /projects/{id}/chat, and can clear history with a delete endpoint.
12. Operational and external integration boundaries
- Email is used for OTP registration and reports, with Gmail SMTP handling outbound messages from the backend.
- CORS and frontend/backend origin separation matter because the frontend is often deployed independently and points at the backend through VITE_API_URL.
- The backend also depends on environment-driven secrets for JWT, S3, Mistral, Redis, and mail credentials, so most infrastructure is configured outside the codebase.
13. How to diagram the main runtime flow
- A user logs in or verifies OTP through the auth router, receives a JWT, and the frontend stores it locally.
- After that, the dashboard and timeline fetch org/project state through authenticated API calls.
- Timeline entries are persisted in SQLite, attachments in S3, embeddings in ChromaDB, and conversational context in Redis.
- The AI chat flow is therefore a composition of four stores/services: relational source data, vector search, LLM generation, and short-lived chat memory.
14. What is most important to preserve in an architecture diagram
- Show the frontend, backend API, and the four backend-side integrations separately: database, object storage, vector store, and cache.
- Keep the AI pipeline distinct from normal CRUD flows, because it reads from timeline content and writes chat history but does not own primary business data.
- Keep organization membership and project membership as separate access boundaries, since they govern nearly every protected operation.
Main entry points: services Services · routes Routes · routers HTTP routers · pipeline.py RAG pipeline
Components 24
Frontend
TanStack Start / React app and UI composition
- App shell · Top-level TanStack Start shell and route runtime
frontend/src/routes/__root.tsx - Route tree · Generated TanStack Router metadata
frontend/src/routeTree.gen.ts - Routes · Public, auth, dashboard, and project timeline screens
frontend/src/routes - API client · Centralized HTTP client with JWT injection and 401 handling
frontend/src/lib/api.ts - Query runtime · TanStack Query integration for prefetching and hydration
frontend/src/router.tsx - Dashboard UI · Authenticated project and organization workspace
frontend/src/components - Timeline UI · Entry creation, detail inspection, and project timeline view
frontend/src/components - Chat panel · Project-scoped chatbot and history hydration
frontend/src/components/TimelineChatbot.tsx - Marketing pages · Landing, about, and report pages plus hero media
frontend/src/routes/index.tsx - Remotion hero · Separate Remotion runtime for landing-page hero video
frontend/remotion
Backend
FastAPI API, services, data model, and RAG pipeline
- API app · ASGI application entrypoint and router assembly
backend/main.py - Auth layer · Bearer auth, OTP registration, and access control dependencies
backend/dependencies/auth.py - HTTP routers · Auth, organizations, projects, timeline, upload, chat, history, and report endpoints
backend/routers - Services · Orchestration for auth, orgs, projects, timeline, uploads, and chat history
backend/services - Models · Users, organizations, projects, membership, timeline entries, links, attachments, and pending registrations
backend/models - Schemas · Request and response shapes for API payloads
backend/schemas - RAG pipeline · Embedding, retrieval, and LLM answer generation for project chat
backend/rag/pipeline.py - Chat history · Temporary project/user chat memory with TTL
backend/services/chat_history_service.py
External systems
Infrastructure and third-party services used by the backend
- SQLite · Primary persistent database for app state
backend/devcycle.db - S3 · Direct-upload file storage via presigned URLs
backend/services/s3_service.py - ChromaDB · Embeddings and project-scoped semantic retrieval
backend/rag/vector_store.py - Redis · Upstash-backed short-lived chat memory store
backend/services/chat_history_service.py - Mistral AI · Generates answers from retrieved project context
backend/rag/llm.py - Gmail SMTP · Outbound OTP and report delivery
backend/services/auth_service.py
Connections 22
- Routes → App shell: mounted in · Routes render inside the top-level shell
- Route tree → Routes: describes · Generated route metadata feeds file routes
- Routes → API client: calls · Screens use the shared HTTP client
- API client → HTTP routers: HTTP/JSON · Authenticated requests go to backend endpoints
- Query runtime → API client: hydrates from · Query runtime shares the API client
- Dashboard UI → Routes: composed in · Dashboard surface is assembled from route components
- Timeline UI → Routes: composed in · Timeline surface is assembled from route components
- Chat panel → Timeline UI: embedded in · Chat panel is part of project timeline UX
- Marketing pages → Remotion hero: uses · Landing page hero relies on the separate Remotion asset runtime
- API app → HTTP routers: registers · ASGI app mounts the HTTP routers
- HTTP routers → Auth layer: protects with · Routes use dependency-based auth checks
- HTTP routers → Services: delegates to · Routers stay thin and call service layer
- Services → Models: reads/writes · Services manipulate persistent domain entities
- Services → Schemas: validates with · Services exchange typed request/response data
- Models → SQLite: persisted in · Relational state lives in SQLite
- Services → S3: uploads to · Presigned upload flow stores files directly in S3
- RAG pipeline → ChromaDB: retrieves from · RAG searches indexed timeline embeddings
- RAG pipeline → Mistral AI: generates with · Retrieved context is sent to the LLM
- Chat history → Redis: stored in · Temporary chat memory is kept in Redis
- Services → RAG pipeline: invokes · Chat endpoints delegate answer generation to the RAG pipeline
- Services → Chat history: appends/reads · Chat services hydrate and update conversation history
- Services → Gmail SMTP: sends · OTP and report emails are delivered through SMTP