# kevalxd/sutra architecture

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

- Interactive diagram: https://gitdiagram.com/kevalxd/sutra
- Repository: https://github.com/kevalxd/sutra

## Overview

Sutra is a frontend prototype for demonstrating travel-disruption recovery. The user journey loads a demo itinerary, presents a disruption and its downstream impact, then retrieves alternatives and requests a recovery result, showing either a feasible repair or why none is feasible. The Next.js routes use local mock data; the recovery engine selects among feasible candidates. UI modules cover itinerary, impact, and recovery presentation. The README describes delay, cancellation, infeasible, and retryable-error scenarios. Some UI and API-client internals were not excerpted, so those connections are omitted or marked unverified.

Main entry points: [`components/sutra/sections.tsx`](https://github.com/kevalxd/sutra/blob/main/components/sutra/sections.tsx) (Journey sections), [`components/sutra/app.tsx`](https://github.com/kevalxd/sutra/blob/main/components/sutra/app.tsx) (Sutra app), [`lib/api.ts`](https://github.com/kevalxd/sutra/blob/main/lib/api.ts) (API client), [`lib/scenario.ts`](https://github.com/kevalxd/sutra/blob/main/lib/scenario.ts) (Scenario parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_page["Scenario page<br/>[page.tsx]"]
  node_app["Sutra app<br/>[app.tsx]"]
  node_sections["Journey sections<br/>[sections.tsx]"]
  node_result["Recovery result views<br/>[result.tsx]"]
  node_journey["Journey band<br/>[journey-band.tsx]"]
  node_affected["Affected bookings<br/>[affected.tsx]"]
  node_comparison["Candidate comparison<br/>[comparison.tsx]"]
  node_recovery_path["Recovery path<br/>[recovery-path.tsx]"]
  node_repair_diff["Repair differences<br/>[repair-diff.tsx]"]
  node_kit["Workflow interactions<br/>[kit.tsx]"]
  node_globe["Travel globe<br/>[travel-globe.tsx]"]
  node_grainient["Background effects<br/>[grainient.tsx]"]
  node_meteors["Meteor effects<br/>[meteors.tsx]"]
end

subgraph group_workflow["Recovery workflow"]
  node_flow["Recovery flow state"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_service["Demo API"]
  node_trip_route["Trip endpoint<br/>[route.ts]"]
  node_disruption_route["Disruption endpoint<br/>[route.ts]"]
  node_alternatives_route["Alternatives endpoint<br/>[route.ts]"]
  node_recovery_route["Recovery endpoint<br/>[route.ts]"]
end

subgraph group_domain["Domain support"]
  node_scenario["Scenario parsing<br/>[scenario.ts]"]
  node_mock["Scenario mock data<br/>[mock.ts]"]
  node_engine["Recovery selection<br/>[engine.ts]"]
  node_format["Date and value formatting<br/>[format.ts]"]
  node_places["Place names<br/>[places.ts]"]
  node_types["Workflow data types<br/>[types.ts]"]
end

node_traveller(("Traveller"))

node_traveller -->|"chooses scenario"| node_page
node_page -->|"parses scenario"| node_scenario
node_page -->|"renders"| node_app
node_app -->|"runs workflow"| node_flow
node_app -->|"renders"| node_sections
node_app -->|"renders"| node_result
node_app -->|"uses interactions"| node_kit
node_app -->|"renders"| node_grainient
node_app -->|"renders"| node_meteors
node_sections -->|"renders"| node_journey
node_sections -->|"renders"| node_affected
node_sections -->|"loads"| node_globe
node_sections -->|"uses stages"| node_kit
node_sections -->|"formats values"| node_format
node_sections -->|"names locations"| node_places
node_flow -->|"requests data"| node_api_client
node_api_client -.->|"calls endpoint"| node_trip_route
node_api_client -.->|"calls endpoint"| node_disruption_route
node_api_client -.->|"calls endpoint"| node_alternatives_route
node_api_client -.->|"calls endpoint"| node_recovery_route
node_trip_route -->|"parses scenario"| node_scenario
node_trip_route -->|"loads trip"| node_mock
node_disruption_route -->|"parses scenario"| node_scenario
node_disruption_route -->|"uses mock data"| node_mock
node_alternatives_route -->|"parses scenario"| node_scenario
node_alternatives_route -->|"loads candidates"| node_mock
node_recovery_route -->|"parses scenario"| node_scenario
node_recovery_route -->|"requests recovery"| node_engine
node_engine -->|"selects candidates"| node_mock
node_engine -->|"uses domain types"| node_types
node_journey -->|"formats journey"| node_format
node_journey -->|"names locations"| node_places
node_journey -->|"uses booking data"| node_types
node_sections -->|"uses workflow data"| node_types
node_result -.->|"may present comparison"| node_comparison
node_result -.->|"may show repair path"| node_recovery_path
node_result -.->|"may show changes"| node_repair_diff

click node_page "https://github.com/kevalxd/sutra/blob/main/app/page.tsx"
click node_app "https://github.com/kevalxd/sutra/blob/main/components/sutra/app.tsx"
click node_sections "https://github.com/kevalxd/sutra/blob/main/components/sutra/sections.tsx"
click node_result "https://github.com/kevalxd/sutra/blob/main/components/sutra/result.tsx"
click node_journey "https://github.com/kevalxd/sutra/blob/main/components/sutra/journey-band.tsx"
click node_affected "https://github.com/kevalxd/sutra/blob/main/components/sutra/affected.tsx"
click node_comparison "https://github.com/kevalxd/sutra/blob/main/components/sutra/comparison.tsx"
click node_recovery_path "https://github.com/kevalxd/sutra/blob/main/components/sutra/recovery-path.tsx"
click node_repair_diff "https://github.com/kevalxd/sutra/blob/main/components/sutra/repair-diff.tsx"
click node_kit "https://github.com/kevalxd/sutra/blob/main/components/sutra/kit.tsx"
click node_globe "https://github.com/kevalxd/sutra/blob/main/components/sutra/travel-globe.tsx"
click node_grainient "https://github.com/kevalxd/sutra/blob/main/components/sutra/grainient.tsx"
click node_meteors "https://github.com/kevalxd/sutra/blob/main/components/ui/meteors.tsx"
click node_flow "https://github.com/kevalxd/sutra/blob/main/hooks/use-recovery-flow.ts"
click node_api_client "https://github.com/kevalxd/sutra/blob/main/lib/api.ts"
click node_trip_route "https://github.com/kevalxd/sutra/blob/main/app/api/trip/route.ts"
click node_disruption_route "https://github.com/kevalxd/sutra/blob/main/app/api/disruption/route.ts"
click node_alternatives_route "https://github.com/kevalxd/sutra/blob/main/app/api/alternatives/route.ts"
click node_recovery_route "https://github.com/kevalxd/sutra/blob/main/app/api/recovery/route.ts"
click node_scenario "https://github.com/kevalxd/sutra/blob/main/lib/scenario.ts"
click node_mock "https://github.com/kevalxd/sutra/blob/main/lib/mock.ts"
click node_engine "https://github.com/kevalxd/sutra/blob/main/lib/engine.ts"
click node_format "https://github.com/kevalxd/sutra/blob/main/lib/format.ts"
click node_places "https://github.com/kevalxd/sutra/blob/main/lib/places.ts"
click node_types "https://github.com/kevalxd/sutra/blob/main/lib/types.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_page,node_app,node_sections,node_result,node_journey,node_affected,node_comparison,node_recovery_path,node_repair_diff,node_kit,node_globe,node_grainient,node_meteors toneBlue
class node_flow,node_api_client toneAmber
class node_trip_route,node_disruption_route,node_alternatives_route,node_recovery_route toneMint
class node_scenario,node_mock,node_engine,node_format,node_places,node_types toneRose
class node_traveller toneIndigo
```

## Components

### User experience

- [Scenario page](https://github.com/kevalxd/sutra/blob/main/app/page.tsx): `app/page.tsx`
- [Sutra app](https://github.com/kevalxd/sutra/blob/main/components/sutra/app.tsx): `components/sutra/app.tsx`
- [Journey sections](https://github.com/kevalxd/sutra/blob/main/components/sutra/sections.tsx): `components/sutra/sections.tsx`
- [Recovery result views](https://github.com/kevalxd/sutra/blob/main/components/sutra/result.tsx): `components/sutra/result.tsx`
- [Journey band](https://github.com/kevalxd/sutra/blob/main/components/sutra/journey-band.tsx): `components/sutra/journey-band.tsx`
- [Affected bookings](https://github.com/kevalxd/sutra/blob/main/components/sutra/affected.tsx): `components/sutra/affected.tsx`
- [Candidate comparison](https://github.com/kevalxd/sutra/blob/main/components/sutra/comparison.tsx): `components/sutra/comparison.tsx`
- [Recovery path](https://github.com/kevalxd/sutra/blob/main/components/sutra/recovery-path.tsx): `components/sutra/recovery-path.tsx`
- [Repair differences](https://github.com/kevalxd/sutra/blob/main/components/sutra/repair-diff.tsx): `components/sutra/repair-diff.tsx`
- [Workflow interactions](https://github.com/kevalxd/sutra/blob/main/components/sutra/kit.tsx): `components/sutra/kit.tsx`
- [Travel globe](https://github.com/kevalxd/sutra/blob/main/components/sutra/travel-globe.tsx): `components/sutra/travel-globe.tsx`
- [Background effects](https://github.com/kevalxd/sutra/blob/main/components/sutra/grainient.tsx): `components/sutra/grainient.tsx`
- [Meteor effects](https://github.com/kevalxd/sutra/blob/main/components/ui/meteors.tsx): `components/ui/meteors.tsx`

### Recovery workflow

- [Recovery flow state](https://github.com/kevalxd/sutra/blob/main/hooks/use-recovery-flow.ts): `hooks/use-recovery-flow.ts`
- [API client](https://github.com/kevalxd/sutra/blob/main/lib/api.ts): `lib/api.ts`

### Demo API

- [Trip endpoint](https://github.com/kevalxd/sutra/blob/main/app/api/trip/route.ts): `app/api/trip/route.ts`
- [Disruption endpoint](https://github.com/kevalxd/sutra/blob/main/app/api/disruption/route.ts): `app/api/disruption/route.ts`
- [Alternatives endpoint](https://github.com/kevalxd/sutra/blob/main/app/api/alternatives/route.ts): `app/api/alternatives/route.ts`
- [Recovery endpoint](https://github.com/kevalxd/sutra/blob/main/app/api/recovery/route.ts): `app/api/recovery/route.ts`

### Domain support

- [Scenario parsing](https://github.com/kevalxd/sutra/blob/main/lib/scenario.ts): `lib/scenario.ts`
- [Scenario mock data](https://github.com/kevalxd/sutra/blob/main/lib/mock.ts): `lib/mock.ts`
- [Recovery selection](https://github.com/kevalxd/sutra/blob/main/lib/engine.ts): `lib/engine.ts`
- [Date and value formatting](https://github.com/kevalxd/sutra/blob/main/lib/format.ts): `lib/format.ts`
- [Place names](https://github.com/kevalxd/sutra/blob/main/lib/places.ts): `lib/places.ts`
- [Workflow data types](https://github.com/kevalxd/sutra/blob/main/lib/types.ts): `lib/types.ts`

### Other components

- **Traveller**

## Connections

- Traveller → Scenario page: chooses scenario (evidence: `README.md`)
- Scenario page → Scenario parsing: parses scenario (evidence: `app/page.tsx`)
- Scenario page → Sutra app: renders (evidence: `app/page.tsx`)
- Sutra app → Recovery flow state: runs workflow (evidence: `components/sutra/app.tsx`)
- Sutra app → Journey sections: renders (evidence: `components/sutra/app.tsx`)
- Sutra app → Recovery result views: renders (evidence: `components/sutra/app.tsx`)
- Sutra app → Workflow interactions: uses interactions (evidence: `components/sutra/app.tsx`)
- Sutra app → Background effects: renders (evidence: `components/sutra/app.tsx`)
- Sutra app → Meteor effects: renders (evidence: `components/sutra/app.tsx`)
- Journey sections → Journey band: renders (evidence: `components/sutra/sections.tsx`)
- Journey sections → Affected bookings: renders (evidence: `components/sutra/sections.tsx`)
- Journey sections → Travel globe: loads (evidence: `components/sutra/sections.tsx`)
- Journey sections → Workflow interactions: uses stages (evidence: `components/sutra/sections.tsx`)
- Journey sections → Date and value formatting: formats values (evidence: `components/sutra/sections.tsx`)
- Journey sections → Place names: names locations (evidence: `components/sutra/sections.tsx`)
- Recovery flow state → API client: requests data (evidence: `hooks/use-recovery-flow.ts`)
- API client → Trip endpoint: calls endpoint
- API client → Disruption endpoint: calls endpoint
- API client → Alternatives endpoint: calls endpoint
- API client → Recovery endpoint: calls endpoint
- Trip endpoint → Scenario parsing: parses scenario (evidence: `app/api/trip/route.ts`)
- Trip endpoint → Scenario mock data: loads trip (evidence: `app/api/trip/route.ts`)
- Disruption endpoint → Scenario parsing: parses scenario
- Disruption endpoint → Scenario mock data: uses mock data
- Alternatives endpoint → Scenario parsing: parses scenario (evidence: `app/api/alternatives/route.ts`)
- Alternatives endpoint → Scenario mock data: loads candidates (evidence: `app/api/alternatives/route.ts`)
- Recovery endpoint → Scenario parsing: parses scenario (evidence: `app/api/recovery/route.ts`)
- Recovery endpoint → Recovery selection: requests recovery (evidence: `app/api/recovery/route.ts`)
- Recovery selection → Scenario mock data: selects candidates (evidence: `lib/engine.ts`)
- Recovery selection → Workflow data types: uses domain types (evidence: `lib/engine.ts`)
- Journey band → Date and value formatting: formats journey (evidence: `components/sutra/journey-band.tsx`)
- Journey band → Place names: names locations (evidence: `components/sutra/journey-band.tsx`)
- Journey band → Workflow data types: uses booking data (evidence: `components/sutra/journey-band.tsx`)
- Journey sections → Workflow data types: uses workflow data (evidence: `components/sutra/sections.tsx`)
- Recovery result views → Candidate comparison: may present comparison
- Recovery result views → Recovery path: may show repair path
- Recovery result views → Repair differences: may show changes
