How rohitg00/time-traveller works
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: completeTeleport.step.ts Teleport flow · apiClient.ts API client · commandParser.ts Gemini services · initiateTeleport.step.ts Teleport API
Components 18
Frontend
React 19 + Vite UI and client state
- App shell · Main UI composition and route-less presentation shell
frontend/App.tsx - Input modes · Manual setup, map selection, image upload, and terminal-style input
frontend/components/ControlPanel.tsx - Auth state · Client-side signed-in state and session gating
frontend/contexts/AuthContext.tsx - API client · Frontend request layer to backend endpoints
frontend/apiClient.ts
Motia Backend
HTTP steps, event chain, and live progress
- Teleport API · Creates teleport jobs and exposes progress and completion reads
steps/api/initiateTeleport.step.ts - Command parse · Converts natural language travel commands into structured requests
steps/api/parseTravelCommand.step.ts - Location info · Synchronous destination enrichment endpoint
steps/api/getLocationInfo.step.ts - History API · User-scoped history and playback retrieval
steps/api/getHistory.step.ts - Auth API · Backend identity exchange and validation boundary
steps/api/auth.step.ts - Progress stream · Live teleport status updates for the UI
steps/streams/teleportProgress.stream.ts - Auth guard · JWT-based protection for private endpoints
steps/middlewares/auth.middleware.ts - Teleport flow · Orchestrates generation and completion after job creation
steps/events/completeTeleport.step.ts - Location step · Builds enriched destination context
steps/events/generateLocationDetails.step.ts - Image step · Generates destination imagery for the completed teleport
steps/events/generateImage.step.ts - Speech step · Synthesizes narration audio for the trip
steps/events/synthesizeSpeech.step.ts
Services
Vendor and domain integrations
- Gemini services · Command parsing, image generation, location prompting, and TTS helpers
services/gemini/commandParser.ts - Maps enrich · Google Maps-based contextual enrichment
services/google/locationEnrichment.ts
Persistence
Supabase-backed auth, storage, and history
- Supabase store · Authentication, history storage, and file storage
services/supabase/authService.ts
Connections 23
- 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