# shivanshdarji/flight-call-bot architecture

> Architecture diagram of the GitHub repository shivanshdarji/flight-call-bot, 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/shivanshdarji/flight-call-bot
- Repository: https://github.com/shivanshdarji/flight-call-bot

## Overview

1. **Overall shape**
   - This repository is a **React + TypeScript frontend** for a flight call-attendant bot, with a **small separate backend layer** under `backend/`.
   - The main user experience appears to be a **single-page app** that simulates or drives customer support workflows for Air Services.

2. **Primary runtime**
   - The client is built with **Vite** (`vite.config.ts`, `src/main.tsx`) and served as a **static site**.
   - Deployment is configured for **Render** via `render.yaml`, which matches the repo’s static-site style deployment.

3. **UI composition**
   - `src/App.tsx` is the top-level orchestrator.
   - The main user flows are split into screen components:
     - `LoginScreen`
     - `DashboardScreen`
     - `ChatWidget`
     - `LookupScreen`
     - `NewBookingScreen`
     - `RebookScreen`
     - `RefundScreen`
     - `DisruptedScreen`
     - `ConfirmationScreen`
   - This suggests the app is organized around **discrete operational workflows** rather than a generic page hierarchy.

4. **Conversation layer**
   - `src/components/ChatWidget.tsx` is the central interaction surface for the bot experience.
   - The README says the app uses the **OpenAI API**, and the environment variable `VITE_OPENAI_API_KEY` indicates the key is used from the **frontend runtime**.
   - The chat layer likely bridges conversational input into the domain screens and actions.

5. **Domain workflows**
   - The named screens indicate the core business domains:
     - **flight lookup / search**
     - **new booking**
     - **rebooking**
     - **refund handling**
     - **disruption management**
     - **confirmation**
   - Architecturally, these appear to be **task-specific UI states** driven by the bot or dashboard, not separate services.

6. **Data model and fixtures**
   - `src/types.ts` defines shared client-side domain types.
   - `src/mockData.ts` implies the app uses **local sample data / simulation data** rather than a visible persistent database in this repo.
   - That points to a mostly **front-end state-driven demo or prototype** architecture.

7. **Backend boundary**
   - There is a separate `backend/src` tree with:
     - `routes/bot.js`
     - `services/escalationRules.js`
   - This suggests the backend is a **thin API/service layer** focused on bot handling and escalation logic, rather than a large standalone system.
   - The presence of `escalationRules` implies business logic for deciding when a bot interaction should be escalated to a human or alternate path.

8. **Likely data flow**
   - User input enters through the **chat widget** or workflow screens.
   - The frontend manages the interaction state, drawing from shared types and mock data.
   - For bot-specific logic, the app likely calls into the **backend bot route**, which in turn uses escalation rules.
   - OpenAI-powered conversational behavior is part of the client configuration, so some AI interaction may happen directly in the browser.

9. **Supportive documentation**
   - `docs/api-docs.md`, `docs/scenario-matrix.md`, and `docs/project_updates_log.md` indicate the repo includes **process and behavior documentation** alongside code.
   - `challenge-1-plan-v2.md` suggests the project was built iteratively around a defined scenario set.

10. **Operational boundaries**
   - There is no sign of a database, queue, auth provider, or third-party workflow engine in the tree.
   - The architecture therefore looks like:
     - **UI/state layer in React**
     - **AI-assisted conversational layer**
     - **small server-side bot/escalation layer**
     - **static deployment**
   - That makes it suitable for diagramming as a **thin-client, workflow-centric application** with limited backend complexity.

11. **Important diagram takeaway**
   - If you draw this system, the key boundary is between:
     - the **browser-based React app** handling screens, conversation, and workflow state
     - and the **backend bot service** handling bot-specific routing/escalation logic
   - Everything else in the repo supports those two halves.

Main entry points: [`src/App.tsx`](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/App.tsx) (App), [`src/main.tsx`](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/main.tsx) (main), [`backend/src/routes/bot.js`](https://github.com/shivanshdarji/flight-call-bot/blob/main/backend/src/routes/bot.js) (Bot route), [`src/components/ChatWidget.tsx`](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/ChatWidget.tsx) (Chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend app"]
  node_src_main["main<br/>Vite entry<br/>[main.tsx]"]
  node_src_app["App<br/>UI orchestrator<br/>[App.tsx]"]
  node_chat_widget["Chat<br/>conversation UI<br/>[ChatWidget.tsx]"]
  node_login_screen["Login<br/>auth screen<br/>[LoginScreen.tsx]"]
  node_dashboard_screen["Dashboard<br/>ops screen"]
  node_lookup_screen["Lookup<br/>search flow<br/>[LookupScreen.tsx]"]
  node_booking_screen["Booking"]
  node_rebook_screen["Rebook<br/>change flow<br/>[RebookScreen.tsx]"]
  node_refund_screen["Refund<br/>[RefundScreen.tsx]"]
  node_disrupted_screen["Disrupted<br/>irregular ops"]
  node_confirmation_screen["Confirmation<br/>result screen"]
  node_types["Types<br/>domain model<br/>[types.ts]"]
  node_mock_data["Mock data<br/>fixtures<br/>[mockData.ts]"]
end

subgraph group_backend["Backend service"]
  node_backend_bot["Bot route<br/>API route<br/>[bot.js]"]
  node_escalation_rules["Escalation<br/>business rules<br/>[escalationRules.js]"]
end

subgraph group_ops["Docs & deploy"]
  node_vite_config["Vite config<br/>build config<br/>[vite.config.ts]"]
  node_render_yaml["Render<br/>deploy config<br/>[render.yaml]"]
  node_api_docs["API docs<br/>[api-docs.md]"]
end

node_src_main -->|"mounts"| node_src_app
node_src_app -->|"uses"| node_chat_widget
node_src_app -->|"routes to"| node_login_screen
node_src_app -->|"routes to"| node_dashboard_screen
node_src_app -->|"routes to"| node_lookup_screen
node_src_app -->|"routes to"| node_booking_screen
node_src_app -->|"routes to"| node_rebook_screen
node_src_app -->|"routes to"| node_refund_screen
node_src_app -->|"routes to"| node_disrupted_screen
node_src_app -->|"routes to"| node_confirmation_screen
node_src_app -->|"shares"| node_types
node_src_app -->|"seeds"| node_mock_data
node_chat_widget -->|"calls"| node_backend_bot
node_backend_bot -->|"uses"| node_escalation_rules
node_src_main -->|"builds with"| node_vite_config
node_render_yaml -.->|"deploys"| node_src_main
node_api_docs -.->|"describes"| node_backend_bot

click node_src_main "https://github.com/shivanshdarji/flight-call-bot/blob/main/src/main.tsx"
click node_src_app "https://github.com/shivanshdarji/flight-call-bot/blob/main/src/App.tsx"
click node_chat_widget "https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/ChatWidget.tsx"
click node_login_screen "https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/LoginScreen.tsx"
click node_dashboard_screen "https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/DashboardScreen.tsx"
click node_lookup_screen "https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/LookupScreen.tsx"
click node_booking_screen "https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/NewBookingScreen.tsx"
click node_rebook_screen "https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/RebookScreen.tsx"
click node_refund_screen "https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/RefundScreen.tsx"
click node_disrupted_screen "https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/DisruptedScreen.tsx"
click node_confirmation_screen "https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/ConfirmationScreen.tsx"
click node_types "https://github.com/shivanshdarji/flight-call-bot/blob/main/src/types.ts"
click node_mock_data "https://github.com/shivanshdarji/flight-call-bot/blob/main/src/mockData.ts"
click node_backend_bot "https://github.com/shivanshdarji/flight-call-bot/blob/main/backend/src/routes/bot.js"
click node_escalation_rules "https://github.com/shivanshdarji/flight-call-bot/blob/main/backend/src/services/escalationRules.js"
click node_vite_config "https://github.com/shivanshdarji/flight-call-bot/blob/main/vite.config.ts"
click node_render_yaml "https://github.com/shivanshdarji/flight-call-bot/blob/main/render.yaml"
click node_api_docs "https://github.com/shivanshdarji/flight-call-bot/blob/main/docs/api-docs.md"

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_src_main,node_src_app,node_chat_widget,node_login_screen,node_dashboard_screen,node_lookup_screen,node_booking_screen,node_rebook_screen,node_refund_screen,node_disrupted_screen,node_confirmation_screen,node_types,node_mock_data toneBlue
class node_backend_bot,node_escalation_rules toneAmber
class node_vite_config,node_render_yaml,node_api_docs toneMint
```

## Components

### Frontend app

React + TypeScript SPA that drives the flight support workflows.

- [main](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/main.tsx): Vite entry · Browser entrypoint that mounts the React app. · `src/main.tsx`
- [App](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/App.tsx): UI orchestrator · Top-level screen and workflow coordinator. · `src/App.tsx`
- [Chat](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/ChatWidget.tsx): conversation UI · Primary bot interaction surface. · `src/components/ChatWidget.tsx`
- [Login](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/LoginScreen.tsx): auth screen · Entry screen for user access. · `src/components/LoginScreen.tsx`
- [Dashboard](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/DashboardScreen.tsx): ops screen · Main task hub for the support flows. · `src/components/DashboardScreen.tsx`
- [Lookup](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/LookupScreen.tsx): search flow · Flight and booking lookup workflow. · `src/components/LookupScreen.tsx`
- [Booking](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/NewBookingScreen.tsx): booking flow · New booking workflow. · `src/components/NewBookingScreen.tsx`
- [Rebook](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/RebookScreen.tsx): change flow · Flight rebooking workflow. · `src/components/RebookScreen.tsx`
- [Refund](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/RefundScreen.tsx): refund flow · Refund handling workflow. · `src/components/RefundScreen.tsx`
- [Disrupted](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/DisruptedScreen.tsx): irregular ops · Disruption handling workflow. · `src/components/DisruptedScreen.tsx`
- [Confirmation](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/components/ConfirmationScreen.tsx): result screen · Final confirmation and success state. · `src/components/ConfirmationScreen.tsx`
- [Types](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/types.ts): domain model · Shared client-side type definitions. · `src/types.ts`
- [Mock data](https://github.com/shivanshdarji/flight-call-bot/blob/main/src/mockData.ts): fixtures · Local sample data used to simulate workflows. · `src/mockData.ts`

### Backend service

Thin server-side layer for bot routing and escalation decisions.

- [Bot route](https://github.com/shivanshdarji/flight-call-bot/blob/main/backend/src/routes/bot.js): API route · Backend endpoint for bot requests. · `backend/src/routes/bot.js`
- [Escalation](https://github.com/shivanshdarji/flight-call-bot/blob/main/backend/src/services/escalationRules.js): business rules · Server-side logic for escalation decisions. · `backend/src/services/escalationRules.js`

### Docs & deploy

Supporting documentation and deployment/runtime configuration.

- [Vite config](https://github.com/shivanshdarji/flight-call-bot/blob/main/vite.config.ts): build config · Client build and dev-server configuration. · `vite.config.ts`
- [Render](https://github.com/shivanshdarji/flight-call-bot/blob/main/render.yaml): deploy config · Static deployment configuration. · `render.yaml`
- [API docs](https://github.com/shivanshdarji/flight-call-bot/blob/main/docs/api-docs.md): docs · Documentation for the service and scenarios. · `docs/api-docs.md`

## Connections

- main → App: mounts · Browser entry mounts the root app.
- App → Chat: uses · App embeds the main conversation surface.
- App → Login: routes to · App can render the login flow.
- App → Dashboard: routes to · App can render the dashboard.
- App → Lookup: routes to · App can render the lookup workflow.
- App → Booking: routes to · App can render the booking workflow.
- App → Rebook: routes to · App can render the rebooking workflow.
- App → Refund: routes to · App can render the refund workflow.
- App → Disrupted: routes to · App can render the disruption workflow.
- App → Confirmation: routes to · App can render the confirmation state.
- App → Types: shares · UI flows use shared domain types.
- App → Mock data: seeds · App state is driven by local fixture data.
- Chat → Bot route: calls · Conversation requests can be sent to the backend bot route.
- Bot route → Escalation: uses · Bot routing relies on escalation logic.
- main → Vite config: builds with · The client is served through Vite.
- Render → main: deploys · Render serves the static frontend build.
- API docs → Bot route: describes · Docs capture the bot API behavior.
