# rapmraran/kel architecture

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

- Interactive diagram: https://gitdiagram.com/rapmraran/kel
- Repository: https://github.com/rapmraran/kel

## Overview

KelanaAI is a travel-planning application with authenticated trip management and AI travel assistance. The user workflow runs from the frontend to the FastAPI endpoints: users can generate and manage saved trips, or ask a conversational or knowledge-base-backed assistant. The graph also captures authentication, persistence, and trip-budget logic. Backend routes and service calls are evidenced in sampled source; some frontend-to-backend and unsampled subsystem links are documented only by the available UI or are left unconnected where evidence is insufficient.

Main entry points: [`backend/main.py`](https://github.com/rapmraran/kel/blob/main/backend/main.py) (FastAPI routes), [`frontend/services`](https://github.com/rapmraran/kel/tree/main/frontend/services) (API clients), [`backend/services/auth_service.py`](https://github.com/rapmraran/kel/blob/main/backend/services/auth_service.py) (Authentication), [`backend/services/kb_service.py`](https://github.com/rapmraran/kel/blob/main/backend/services/kb_service.py) (Knowledge retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_web["Next.js pages"]
  node_trip_ui["Trip dashboard<br/>[TripDashboard.tsx]"]
  node_trip_card["Trip card<br/>[TripCard.tsx]"]
  node_trip_forms["Trip forms"]
  node_chat_ui["Chat dashboard<br/>[ChatDashboard.tsx]"]
  node_auth_ui["Auth pages<br/>[page.tsx]"]
  node_frontend_services["API clients"]
end

subgraph group_api["Backend API"]
  node_api["FastAPI routes<br/>[main.py]"]
end

subgraph group_planning["Trip planning"]
  node_trip_rules["Trip rules<br/>[trip_service.py]"]
  node_trip_service["Trip operations<br/>[trip_service.py]"]
end

subgraph group_assistant["AI assistance"]
  node_rag["Knowledge retrieval<br/>[kb_service.py]"]
  node_bedrock["Base model and chat<br/>[bedrock_service.py]"]
end

subgraph group_persistence["Identity and data"]
  node_auth_service["Authentication<br/>[auth_service.py]"]
  node_database[("SQLAlchemy database<br/>[database.py]")]
  node_user_model["User records<br/>[user.py]"]
  node_trip_model["Trip records<br/>[trip.py]"]
  node_conversation_model["Conversation records<br/>[conversation.py]"]
end

node_traveler(("Traveler"))
node_bedrock_service{{"AWS Bedrock"}}

node_traveler -.->|"uses"| node_web
node_trip_ui -->|"renders"| node_trip_card
node_traveler -.->|"browses trips"| node_trip_ui
node_traveler -.->|"chats"| node_chat_ui
node_web -.->|"uses"| node_frontend_services
node_frontend_services -.->|"HTTP requests"| node_api
node_trip_forms -.->|"submits trip data"| node_frontend_services
node_chat_ui -.->|"sends messages"| node_frontend_services
node_auth_ui -.->|"auth requests"| node_frontend_services
node_api -->|"calculates trip details"| node_trip_rules
node_api -.->|"manages trips"| node_trip_service
node_api -->|"retrieves answers"| node_rag
node_api -.->|"generates base answers"| node_bedrock
node_api -.->|"authenticates users"| node_auth_service
node_api -->|"queries and writes"| node_database
node_auth_service -->|"opens sessions"| node_database
node_auth_service -->|"queries users"| node_user_model
node_api -->|"reads and writes"| node_trip_model
node_api -->|"reads and writes"| node_conversation_model
node_rag -.->|"retrieves knowledge"| node_bedrock_service
node_bedrock -.->|"serves retrieval"| node_rag

click node_web "https://github.com/rapmraran/kel/tree/main/frontend/app"
click node_trip_ui "https://github.com/rapmraran/kel/blob/main/frontend/components/TripDashboard.tsx"
click node_trip_card "https://github.com/rapmraran/kel/blob/main/frontend/components/TripCard.tsx"
click node_trip_forms "https://github.com/rapmraran/kel/tree/main/frontend/components"
click node_chat_ui "https://github.com/rapmraran/kel/blob/main/frontend/components/ChatDashboard.tsx"
click node_auth_ui "https://github.com/rapmraran/kel/blob/main/frontend/app/login/page.tsx"
click node_frontend_services "https://github.com/rapmraran/kel/tree/main/frontend/services"
click node_api "https://github.com/rapmraran/kel/blob/main/backend/main.py"
click node_trip_rules "https://github.com/rapmraran/kel/blob/main/backend/services/trip_service.py"
click node_trip_service "https://github.com/rapmraran/kel/blob/main/backend/services/trip_service.py"
click node_rag "https://github.com/rapmraran/kel/blob/main/backend/services/kb_service.py"
click node_bedrock "https://github.com/rapmraran/kel/blob/main/backend/services/bedrock_service.py"
click node_auth_service "https://github.com/rapmraran/kel/blob/main/backend/services/auth_service.py"
click node_database "https://github.com/rapmraran/kel/blob/main/backend/database.py"
click node_user_model "https://github.com/rapmraran/kel/blob/main/backend/models/user.py"
click node_trip_model "https://github.com/rapmraran/kel/blob/main/backend/models/trip.py"
click node_conversation_model "https://github.com/rapmraran/kel/blob/main/backend/models/conversation.py"

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_web,node_trip_ui,node_trip_card,node_trip_forms,node_chat_ui,node_auth_ui,node_frontend_services toneBlue
class node_api toneAmber
class node_trip_rules,node_trip_service toneMint
class node_rag,node_bedrock toneRose
class node_auth_service,node_database,node_user_model,node_trip_model,node_conversation_model,node_traveler,node_bedrock_service toneIndigo
```

## Components

### Web application

- [Next.js pages](https://github.com/rapmraran/kel/tree/main/frontend/app): `frontend/app`
- [Trip dashboard](https://github.com/rapmraran/kel/blob/main/frontend/components/TripDashboard.tsx): `frontend/components/TripDashboard.tsx`
- [Trip card](https://github.com/rapmraran/kel/blob/main/frontend/components/TripCard.tsx): `frontend/components/TripCard.tsx`
- [Trip forms](https://github.com/rapmraran/kel/tree/main/frontend/components): `frontend/components`
- [Chat dashboard](https://github.com/rapmraran/kel/blob/main/frontend/components/ChatDashboard.tsx): `frontend/components/ChatDashboard.tsx`
- [Auth pages](https://github.com/rapmraran/kel/blob/main/frontend/app/login/page.tsx): `frontend/app/login/page.tsx`
- [API clients](https://github.com/rapmraran/kel/tree/main/frontend/services): `frontend/services`

### Backend API

- [FastAPI routes](https://github.com/rapmraran/kel/blob/main/backend/main.py): `backend/main.py`

### Trip planning

- [Trip rules](https://github.com/rapmraran/kel/blob/main/backend/services/trip_service.py): `backend/services/trip_service.py`
- [Trip operations](https://github.com/rapmraran/kel/blob/main/backend/services/trip_service.py): `backend/services/trip_service.py`

### AI assistance

- [Knowledge retrieval](https://github.com/rapmraran/kel/blob/main/backend/services/kb_service.py): `backend/services/kb_service.py`
- [Base model and chat](https://github.com/rapmraran/kel/blob/main/backend/services/bedrock_service.py): `backend/services/bedrock_service.py`

### Identity and data

- [Authentication](https://github.com/rapmraran/kel/blob/main/backend/services/auth_service.py): `backend/services/auth_service.py`
- [SQLAlchemy database](https://github.com/rapmraran/kel/blob/main/backend/database.py): `backend/database.py`
- [User records](https://github.com/rapmraran/kel/blob/main/backend/models/user.py): `backend/models/user.py`
- [Trip records](https://github.com/rapmraran/kel/blob/main/backend/models/trip.py): `backend/models/trip.py`
- [Conversation records](https://github.com/rapmraran/kel/blob/main/backend/models/conversation.py): `backend/models/conversation.py`

### Other components

- **Traveler**
- **AWS Bedrock**

## Connections

- Traveler → Next.js pages: uses
- Trip dashboard → Trip card: renders (evidence: `frontend/components/TripDashboard.tsx`)
- Traveler → Trip dashboard: browses trips
- Traveler → Chat dashboard: chats
- Next.js pages → API clients: uses
- API clients → FastAPI routes: HTTP requests
- Trip forms → API clients: submits trip data
- Chat dashboard → API clients: sends messages
- Auth pages → API clients: auth requests
- FastAPI routes → Trip rules: calculates trip details (evidence: `backend/main.py`)
- FastAPI routes → Trip operations: manages trips (evidence: `backend/main.py`)
- FastAPI routes → Knowledge retrieval: retrieves answers (evidence: `backend/main.py`)
- FastAPI routes → Base model and chat: generates base answers (evidence: `backend/main.py`)
- FastAPI routes → Authentication: authenticates users (evidence: `backend/main.py`)
- FastAPI routes → SQLAlchemy database: queries and writes (evidence: `backend/main.py`)
- Authentication → SQLAlchemy database: opens sessions (evidence: `backend/services/auth_service.py`)
- Authentication → User records: queries users (evidence: `backend/services/auth_service.py`)
- FastAPI routes → Trip records: reads and writes (evidence: `backend/main.py`)
- FastAPI routes → Conversation records: reads and writes (evidence: `backend/main.py`)
- Knowledge retrieval → AWS Bedrock: retrieves knowledge
- Base model and chat → Knowledge retrieval: serves retrieval
