# rohitg00/time-traveller architecture

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

- Interactive diagram: https://gitdiagram.com/rohitg00/time-traveller
- Repository: https://github.com/rohitg00/time-traveller

## Overview

1. **This repo is a two-tier app with a clear split between UI and orchestration.**  
   The `frontend/` directory is a React 19 + Vite single-page app, while `steps/` is a Motia backend that exposes APIs, runs background event chains, and streams progress updates. The architecture is centered on a “teleport” workflow rather than a generic CRUD app.

2. **The frontend is a stateful presentation shell for three user input modes.**  
   Components like `MapSelector`, `TravelerIdentity`, `MultiImageUpload`, `ControlPanel`, and `ViewScreen` support manual setup, map-based exploration, and terminal-style natural language input. `AuthContext` manages signed-in state, and `apiClient.ts` is the main boundary for backend calls.

3. **The main backend boundary is Motia’s step model.**  
   `steps/api/` contains synchronous HTTP endpoints such as `/teleport`, `/auth`, `/user`, `/history`, `/location/info`, `/parse-command`, `/audio`, and `/health`. `steps/events/` contains the asynchronous processing chain that performs the actual AI and media generation work after a teleport request is accepted.

4. **Teleport creation is an orchestrated workflow, not a single request-response call.**  
   The likely flow is: frontend submits a teleport request → `initiateTeleport.step.ts` creates a job → event steps generate location details, synthesize speech, generate the image, and then `completeTeleport` finalizes the result. `steps/streams/teleportProgress.stream.ts` exposes live progress so the UI can show the trip as it is being assembled.

5. **Business logic is intentionally factored into service modules by vendor and domain.**  
   `services/gemini/` isolates AI-specific behavior: command parsing, image generation, location prompts, and text-to-speech. `services/google/locationEnrichment.ts` handles Google Maps-related enrichment, and `services/supabase/` encapsulates authentication, history storage, and file storage. This keeps steps thin and makes vendor integration replaceable.

6. **Authentication and user isolation are a first-class boundary.**  
   Supabase OAuth is used on the frontend, then `steps/api/auth.step.ts` and `steps/middlewares/auth.middleware.ts` establish/validate backend identity using JWTs. Private history is scoped by user, so `/history` and related media retrievals are protected by auth rather than being globally readable.

7. **Media generation and storage are separated from the UI lifecycle.**  
   Generated images, audio narrations, uploaded reference photos, and travel history records are stored in Supabase-backed services rather than kept only in the browser. That makes the backend the source of truth for completed teleports, while the frontend just renders and plays back the stored artifacts.

8. **Location intelligence is an independent subflow that enriches the travel scene.**  
   The `/location/info` endpoint and `getLocationInfo` step gather contextual data like weather, air quality, and nearby places. This data feeds both the visualization experience and the AI prompt context, which means the “destination” is more than a coordinate—it is a synthesized environment.

9. **Terminal mode is powered by natural-language parsing before teleport orchestration.**  
   `parseTravelCommand.step.ts` likely converts phrases like “Take me to Paris in 1889” into structured parameters. That parsed payload then becomes input to the same teleport pipeline used by the other modes, so the natural-language feature is an alternate entry point, not a separate backend path.

10. **The UI is designed to consume live status and completed artifacts separately.**  
   Real-time progress comes through streams, while final results come from REST endpoints like `/teleport/:id` and `/teleport/:id/audio`. This separation lets the app show incremental status, then switch to the final image, narration, and history entry once the job completes.

11. **There is a clean runtime boundary between local development and deployment targets.**  
   The frontend is deployed to Vercel, while the backend is intended for Motia Cloud, with a GitHub Actions workflow in `.github/workflows/deploy.yml`. The architecture assumes distinct public endpoints for the UI, API, and stream channel, configured via environment variables.

12. **The repository also includes developer tooling and reproducible assets, but they are secondary to runtime architecture.**  
   The `scripts/` folder generates showcase imagery for the docs and demo assets, and the `docs/img/` directory supports the product story. These assets help explain the product but do not participate in the production request flow.

13. **At a diagram level, the key boundaries are: browser UI, Motia API/stream backend, vendor AI/maps services, and private persistence.**  
   The essential data flow is user input in React → backend step orchestration → external APIs for AI/maps/auth → Supabase storage/history → streamed progress and final results back to the UI. That is the core architecture to represent accurately.

Main entry points: [`steps/events/completeTeleport.step.ts`](https://github.com/rohitg00/time-traveller/blob/main/steps/events/completeTeleport.step.ts) (Teleport flow), [`frontend/apiClient.ts`](https://github.com/rohitg00/time-traveller/blob/main/frontend/apiClient.ts) (API client), [`services/gemini/commandParser.ts`](https://github.com/rohitg00/time-traveller/blob/main/services/gemini/commandParser.ts) (Gemini services), [`steps/api/initiateTeleport.step.ts`](https://github.com/rohitg00/time-traveller/blob/main/steps/api/initiateTeleport.step.ts) (Teleport API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app_shell["App shell<br/>react spa<br/>[App.tsx]"]
  node_ui_modes["Input modes<br/>ui components<br/>[ControlPanel.tsx]"]
  node_auth_context["Auth state<br/>react context<br/>[AuthContext.tsx]"]
  node_api_client["API client<br/>client boundary<br/>[apiClient.ts]"]
end

subgraph group_backend["Motia Backend"]
  node_teleport_api["Teleport API<br/>motia api"]
  node_command_api["Command parse<br/>motia api"]
  node_location_api["Location info<br/>motia api"]
  node_history_api["History API<br/>motia api<br/>[getHistory.step.ts]"]
  node_auth_api["Auth API<br/>motia api<br/>[auth.step.ts]"]
  node_progress_stream["Progress stream<br/>realtime stream"]
  node_auth_guard["Auth guard<br/>middleware<br/>[auth.middleware.ts]"]
  node_teleport_flow["Teleport flow<br/>event chain"]
  node_location_step["Location step<br/>event step"]
  node_image_step["Image step<br/>event step"]
  node_speech_step["Speech step<br/>event step"]
end

subgraph group_services["Services"]
  node_gemini_ai["Gemini services<br/>ai adapters<br/>[commandParser.ts]"]
  node_maps_enrich["Maps enrich<br/>geo service"]
end

subgraph group_persistence["Persistence"]
  node_supabase_store[("Supabase store<br/>auth + data<br/>[authService.ts]")]
end

subgraph group_deploy["Deploy"]
end

node_app_shell -->|"renders"| node_ui_modes
node_app_shell -->|"uses"| node_auth_context
node_ui_modes -->|"submits"| node_api_client
node_auth_context -->|"authenticates"| node_auth_api
node_api_client -->|"POST /teleport"| node_teleport_api
node_api_client -->|"POST /parse-command"| node_command_api
node_api_client -->|"GET /location/info"| node_location_api
node_api_client -->|"GET /history"| node_history_api
node_teleport_api -->|"protects"| node_auth_guard
node_teleport_api -->|"starts"| node_teleport_flow
node_command_api -->|"parses with"| node_gemini_ai
node_location_api -->|"enriches with"| node_maps_enrich
node_history_api -->|"reads/writes"| node_supabase_store
node_auth_api -->|"validates"| node_supabase_store
node_teleport_flow -->|"runs"| node_location_step
node_teleport_flow -->|"runs"| node_image_step
node_teleport_flow -->|"runs"| node_speech_step
node_location_step -->|"uses"| node_gemini_ai
node_image_step -->|"uses"| node_gemini_ai
node_speech_step -->|"uses"| node_gemini_ai
node_teleport_flow -->|"persists"| node_supabase_store
node_teleport_flow -->|"publishes"| node_progress_stream
node_progress_stream -->|"updates"| node_app_shell

click node_app_shell "https://github.com/rohitg00/time-traveller/blob/main/frontend/App.tsx"
click node_ui_modes "https://github.com/rohitg00/time-traveller/blob/main/frontend/components/ControlPanel.tsx"
click node_auth_context "https://github.com/rohitg00/time-traveller/blob/main/frontend/contexts/AuthContext.tsx"
click node_api_client "https://github.com/rohitg00/time-traveller/blob/main/frontend/apiClient.ts"
click node_teleport_api "https://github.com/rohitg00/time-traveller/blob/main/steps/api/initiateTeleport.step.ts"
click node_command_api "https://github.com/rohitg00/time-traveller/blob/main/steps/api/parseTravelCommand.step.ts"
click node_location_api "https://github.com/rohitg00/time-traveller/blob/main/steps/api/getLocationInfo.step.ts"
click node_history_api "https://github.com/rohitg00/time-traveller/blob/main/steps/api/getHistory.step.ts"
click node_auth_api "https://github.com/rohitg00/time-traveller/blob/main/steps/api/auth.step.ts"
click node_progress_stream "https://github.com/rohitg00/time-traveller/blob/main/steps/streams/teleportProgress.stream.ts"
click node_auth_guard "https://github.com/rohitg00/time-traveller/blob/main/steps/middlewares/auth.middleware.ts"
click node_teleport_flow "https://github.com/rohitg00/time-traveller/blob/main/steps/events/completeTeleport.step.ts"
click node_location_step "https://github.com/rohitg00/time-traveller/blob/main/steps/events/generateLocationDetails.step.ts"
click node_image_step "https://github.com/rohitg00/time-traveller/blob/main/steps/events/generateImage.step.ts"
click node_speech_step "https://github.com/rohitg00/time-traveller/blob/main/steps/events/synthesizeSpeech.step.ts"
click node_gemini_ai "https://github.com/rohitg00/time-traveller/blob/main/services/gemini/commandParser.ts"
click node_maps_enrich "https://github.com/rohitg00/time-traveller/blob/main/services/google/locationEnrichment.ts"
click node_supabase_store "https://github.com/rohitg00/time-traveller/blob/main/services/supabase/authService.ts"

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_app_shell,node_ui_modes,node_auth_context,node_api_client toneBlue
class node_teleport_api,node_command_api,node_location_api,node_history_api,node_auth_api,node_progress_stream,node_auth_guard,node_teleport_flow,node_location_step,node_image_step,node_speech_step toneAmber
class node_gemini_ai,node_maps_enrich toneMint
class node_supabase_store toneRose
```

## Components

### Frontend

React 19 + Vite UI and client state

- [App shell](https://github.com/rohitg00/time-traveller/blob/main/frontend/App.tsx): react spa · Main UI composition and route-less presentation shell · `frontend/App.tsx`
- [Input modes](https://github.com/rohitg00/time-traveller/blob/main/frontend/components/ControlPanel.tsx): ui components · Manual setup, map selection, image upload, and terminal-style input · `frontend/components/ControlPanel.tsx`
- [Auth state](https://github.com/rohitg00/time-traveller/blob/main/frontend/contexts/AuthContext.tsx): react context · Client-side signed-in state and session gating · `frontend/contexts/AuthContext.tsx`
- [API client](https://github.com/rohitg00/time-traveller/blob/main/frontend/apiClient.ts): client boundary · Frontend request layer to backend endpoints · `frontend/apiClient.ts`

### Motia Backend

HTTP steps, event chain, and live progress

- [Teleport API](https://github.com/rohitg00/time-traveller/blob/main/steps/api/initiateTeleport.step.ts): motia api · Creates teleport jobs and exposes progress and completion reads · `steps/api/initiateTeleport.step.ts`
- [Command parse](https://github.com/rohitg00/time-traveller/blob/main/steps/api/parseTravelCommand.step.ts): motia api · Converts natural language travel commands into structured requests · `steps/api/parseTravelCommand.step.ts`
- [Location info](https://github.com/rohitg00/time-traveller/blob/main/steps/api/getLocationInfo.step.ts): motia api · Synchronous destination enrichment endpoint · `steps/api/getLocationInfo.step.ts`
- [History API](https://github.com/rohitg00/time-traveller/blob/main/steps/api/getHistory.step.ts): motia api · User-scoped history and playback retrieval · `steps/api/getHistory.step.ts`
- [Auth API](https://github.com/rohitg00/time-traveller/blob/main/steps/api/auth.step.ts): motia api · Backend identity exchange and validation boundary · `steps/api/auth.step.ts`
- [Progress stream](https://github.com/rohitg00/time-traveller/blob/main/steps/streams/teleportProgress.stream.ts): realtime stream · Live teleport status updates for the UI · `steps/streams/teleportProgress.stream.ts`
- [Auth guard](https://github.com/rohitg00/time-traveller/blob/main/steps/middlewares/auth.middleware.ts): middleware · JWT-based protection for private endpoints · `steps/middlewares/auth.middleware.ts`
- [Teleport flow](https://github.com/rohitg00/time-traveller/blob/main/steps/events/completeTeleport.step.ts): event chain · Orchestrates generation and completion after job creation · `steps/events/completeTeleport.step.ts`
- [Location step](https://github.com/rohitg00/time-traveller/blob/main/steps/events/generateLocationDetails.step.ts): event step · Builds enriched destination context · `steps/events/generateLocationDetails.step.ts`
- [Image step](https://github.com/rohitg00/time-traveller/blob/main/steps/events/generateImage.step.ts): event step · Generates destination imagery for the completed teleport · `steps/events/generateImage.step.ts`
- [Speech step](https://github.com/rohitg00/time-traveller/blob/main/steps/events/synthesizeSpeech.step.ts): event step · Synthesizes narration audio for the trip · `steps/events/synthesizeSpeech.step.ts`

### Services

Vendor and domain integrations

- [Gemini services](https://github.com/rohitg00/time-traveller/blob/main/services/gemini/commandParser.ts): ai adapters · Command parsing, image generation, location prompting, and TTS helpers · `services/gemini/commandParser.ts`
- [Maps enrich](https://github.com/rohitg00/time-traveller/blob/main/services/google/locationEnrichment.ts): geo service · Google Maps-based contextual enrichment · `services/google/locationEnrichment.ts`

### Persistence

Supabase-backed auth, storage, and history

- [Supabase store](https://github.com/rohitg00/time-traveller/blob/main/services/supabase/authService.ts): auth + data · Authentication, history storage, and file storage · `services/supabase/authService.ts`

## Connections

- App shell → Input modes: renders · Composes the interactive input and viewing surfaces
- App shell → Auth state: uses · Reads signed-in state for gated UI behavior
- Input modes → API client: submits · Sends teleport, command, and metadata requests
- Auth state → Auth API: authenticates · Establishes backend identity and session state
- API client → Teleport API: POST /teleport · Creates a teleport job
- API client → Command parse: POST /parse-command · Parses terminal-style requests
- API client → Location info: GET /location/info · Fetches destination context
- API client → History API: GET /history · Loads private trip history
- Teleport API → Auth guard: protects · Requires authenticated access for private operations
- Teleport API → Teleport flow: starts · Queues the async teleport orchestration
- Command parse → Gemini services: parses with · Uses AI command interpretation helpers
- Location info → Maps enrich: enriches with · Adds weather, places, and other destination context
- History API → Supabase store: reads/writes · Retrieves user-scoped history and stored artifacts
- Auth API → Supabase store: validates · Uses Supabase auth as the identity source
- Teleport flow → Location step: runs · Creates enriched destination details
- Teleport flow → Image step: runs · Generates the destination image
- Teleport flow → Speech step: runs · Generates narration audio
- Location step → Gemini services: uses · Builds AI prompts and structured location text
- Image step → Gemini services: uses · Calls image generation helpers
- Speech step → Gemini services: uses · Calls text-to-speech helpers
- Teleport flow → Supabase store: persists · Stores completed results and history records
- Teleport flow → Progress stream: publishes · Streams live status as the job advances
- Progress stream → App shell: updates · Feeds incremental progress back to the UI
