# johnihb/nepal-horizon architecture

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

- Interactive diagram: https://gitdiagram.com/johnihb/nepal-horizon
- Repository: https://github.com/johnihb/nepal-horizon

## Overview

Nepal Horizon is a tourism platform for discovering and booking Nepal adventure packages, with an admin field-office console for managing journeys, images, reservations, and analytics. The traveller flow runs from package browsing and detail to booking and viewing personal reservations; administrators manage packages and bookings, upload imagery directly to Cloudinary, and inspect reporting. The graph combines README-documented capabilities with sampled controller and page behavior. Several route, auth, and analytics implementations were not sampled, so their internal connections are omitted where evidence is unavailable.

Main entry points: [`backend/controllers/user.controller.ts`](https://github.com/johnihb/nepal-horizon/blob/main/backend/controllers/user.controller.ts) (Traveller endpoints), [`backend/server.ts`](https://github.com/johnihb/nepal-horizon/blob/main/backend/server.ts) (Express API), [`backend/controllers/admin.controller.ts`](https://github.com/johnihb/nepal-horizon/blob/main/backend/controllers/admin.controller.ts) (Admin endpoints), [`frontend/lib/auth-client.ts`](https://github.com/johnihb/nepal-horizon/blob/main/frontend/lib/auth-client.ts) (Auth client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_traveller["Traveller journeys"]
  node_packages["Package catalogue<br/>[home.tsx]"]
  node_detail["Package detail<br/>[package.tsx]"]
  node_booking_form["Booking form<br/>[booking.tsx]"]
  node_my_bookings["My bookings<br/>[bookings.tsx]"]
  node_comparison["Package comparison<br/>[compare.tsx]"]
end

subgraph group_identity["Identity and access"]
  node_auth_ui["Auth screens<br/>[login.tsx]"]
  node_auth_client["Auth client<br/>[auth-client.ts]"]
  node_session["Session and roles<br/>[session.ts]"]
end

subgraph group_operations["Field office"]
  node_admin_console["Package admin<br/>[admin.tsx]"]
  node_admin_bookings["Booking queue<br/>[bookings.tsx]"]
  node_analytics_ui["Analytics dashboard<br/>[page.tsx]"]
  node_upload_ui["Image upload UI<br/>[page.tsx]"]
end

subgraph group_backend["Backend services"]
  node_api_server["Express API<br/>[server.ts]"]
  node_user_api["Traveller endpoints<br/>[user.controller.ts]"]
  node_admin_api["Admin endpoints"]
  node_image_api["Image endpoints"]
  node_analytics_api["Analytics endpoints"]
end

subgraph group_integrations["External services"]
  node_database[("PostgreSQL data<br/>[prisma.ts]")]
  node_cloudinary["Cloudinary"]
  node_auth_service["Better Auth<br/>[auth.ts]"]
end

node_traveller(("Traveller"))

node_traveller -->|"browses"| node_packages
node_packages -->|"requests listings"| node_user_api
node_user_api -->|"reads packages"| node_database
node_traveller -->|"opens journey"| node_detail
node_detail -->|"requests details"| node_user_api
node_traveller -->|"books journey"| node_booking_form
node_booking_form -->|"submits booking"| node_user_api
node_user_api -->|"creates booking"| node_database
node_traveller -->|"views reservations"| node_my_bookings
node_my_bookings -->|"requests reservations"| node_user_api
node_traveller -->|"compares packages"| node_comparison
node_traveller -->|"signs in"| node_auth_ui
node_auth_ui -->|"uses client"| node_auth_client
node_auth_client -->|"authenticates"| node_auth_service
node_session -->|"reads session"| node_auth_client
node_admin_console -->|"manages packages"| node_admin_api
node_admin_api -->|"reads and writes"| node_database
node_admin_api -->|"validates and deletes assets"| node_cloudinary
node_admin_bookings -->|"manages bookings"| node_admin_api
node_analytics_ui -->|"requests reports"| node_analytics_api
node_analytics_ui -->|"loads popularity data"| node_admin_bookings
node_upload_ui -->|"requests signature"| node_image_api
node_image_api -->|"signs and deletes"| node_cloudinary
node_api_server -->|"mounts auth"| node_auth_service
node_api_server -->|"mounts admin routes"| node_admin_api
node_api_server -->|"mounts user routes"| node_user_api
node_api_server -->|"mounts image routes"| node_image_api
node_api_server -->|"mounts analytics routes"| node_analytics_api

click node_packages "https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(tour%20packages)/packages/home.tsx"
click node_detail "https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(tour%20packages)/package/%5Bid%5D/package.tsx"
click node_booking_form "https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(tour%20packages)/package/booking/%5Bid%5D/booking.tsx"
click node_my_bookings "https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(user)/bookings/bookings.tsx"
click node_comparison "https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(tour%20packages)/compare/compare.tsx"
click node_auth_ui "https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(auth)/login/login.tsx"
click node_auth_client "https://github.com/johnihb/nepal-horizon/blob/main/frontend/lib/auth-client.ts"
click node_session "https://github.com/johnihb/nepal-horizon/blob/main/frontend/hooks/session.ts"
click node_admin_console "https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(admin)/admin/admin.tsx"
click node_admin_bookings "https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(admin)/admin/bookings/bookings.tsx"
click node_analytics_ui "https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(admin)/dashboard/page.tsx"
click node_upload_ui "https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(admin)/upload/page.tsx"
click node_api_server "https://github.com/johnihb/nepal-horizon/blob/main/backend/server.ts"
click node_user_api "https://github.com/johnihb/nepal-horizon/blob/main/backend/controllers/user.controller.ts"
click node_admin_api "https://github.com/johnihb/nepal-horizon/blob/main/backend/controllers/admin.controller.ts"
click node_image_api "https://github.com/johnihb/nepal-horizon/blob/main/backend/controllers/image.controller.ts"
click node_analytics_api "https://github.com/johnihb/nepal-horizon/blob/main/backend/controllers/bookingAnalytics.controller.ts"
click node_database "https://github.com/johnihb/nepal-horizon/blob/main/backend/lib/prisma.ts"
click node_auth_service "https://github.com/johnihb/nepal-horizon/blob/main/backend/lib/auth.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_packages,node_detail,node_booking_form,node_my_bookings,node_comparison toneBlue
class node_auth_ui,node_auth_client,node_session toneAmber
class node_admin_console,node_admin_bookings,node_analytics_ui,node_upload_ui toneMint
class node_api_server,node_user_api,node_admin_api,node_image_api,node_analytics_api toneRose
class node_database,node_cloudinary,node_auth_service,node_traveller toneIndigo
```

## Components

### Traveller journeys

- [Package catalogue](https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(tour%20packages)/packages/home.tsx): `frontend/app/(tour packages)/packages/home.tsx`
- [Package detail](https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(tour%20packages)/package/%5Bid%5D/package.tsx): `frontend/app/(tour packages)/package/[id]/package.tsx`
- [Booking form](https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(tour%20packages)/package/booking/%5Bid%5D/booking.tsx): `frontend/app/(tour packages)/package/booking/[id]/booking.tsx`
- [My bookings](https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(user)/bookings/bookings.tsx): `frontend/app/(user)/bookings/bookings.tsx`
- [Package comparison](https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(tour%20packages)/compare/compare.tsx): `frontend/app/(tour packages)/compare/compare.tsx`

### Identity and access

- [Auth screens](https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(auth)/login/login.tsx): `frontend/app/(auth)/login/login.tsx`
- [Auth client](https://github.com/johnihb/nepal-horizon/blob/main/frontend/lib/auth-client.ts): `frontend/lib/auth-client.ts`
- [Session and roles](https://github.com/johnihb/nepal-horizon/blob/main/frontend/hooks/session.ts): `frontend/hooks/session.ts`

### Field office

- [Package admin](https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(admin)/admin/admin.tsx): `frontend/app/(admin)/admin/admin.tsx`
- [Booking queue](https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(admin)/admin/bookings/bookings.tsx): `frontend/app/(admin)/admin/bookings/bookings.tsx`
- [Analytics dashboard](https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(admin)/dashboard/page.tsx): `frontend/app/(admin)/dashboard/page.tsx`
- [Image upload UI](https://github.com/johnihb/nepal-horizon/blob/main/frontend/app/(admin)/upload/page.tsx): `frontend/app/(admin)/upload/page.tsx`

### Backend services

- [Express API](https://github.com/johnihb/nepal-horizon/blob/main/backend/server.ts): `backend/server.ts`
- [Traveller endpoints](https://github.com/johnihb/nepal-horizon/blob/main/backend/controllers/user.controller.ts): `backend/controllers/user.controller.ts`
- [Admin endpoints](https://github.com/johnihb/nepal-horizon/blob/main/backend/controllers/admin.controller.ts): `backend/controllers/admin.controller.ts`
- [Image endpoints](https://github.com/johnihb/nepal-horizon/blob/main/backend/controllers/image.controller.ts): `backend/controllers/image.controller.ts`
- [Analytics endpoints](https://github.com/johnihb/nepal-horizon/blob/main/backend/controllers/bookingAnalytics.controller.ts): `backend/controllers/bookingAnalytics.controller.ts`

### External services

- [PostgreSQL data](https://github.com/johnihb/nepal-horizon/blob/main/backend/lib/prisma.ts): `backend/lib/prisma.ts`
- **Cloudinary**
- [Better Auth](https://github.com/johnihb/nepal-horizon/blob/main/backend/lib/auth.ts): `backend/lib/auth.ts`

### Other components

- **Traveller**

## Connections

- Traveller → Package catalogue: browses (evidence: `README.md`)
- Package catalogue → Traveller endpoints: requests listings (evidence: `README.md`)
- Traveller endpoints → PostgreSQL data: reads packages (evidence: `backend/controllers/user.controller.ts`)
- Traveller → Package detail: opens journey (evidence: `README.md`)
- Package detail → Traveller endpoints: requests details
- Traveller → Booking form: books journey (evidence: `README.md`)
- Booking form → Traveller endpoints: submits booking (evidence: `README.md`)
- Traveller endpoints → PostgreSQL data: creates booking (evidence: `backend/controllers/user.controller.ts`)
- Traveller → My bookings: views reservations (evidence: `README.md`)
- My bookings → Traveller endpoints: requests reservations (evidence: `README.md`)
- Traveller → Package comparison: compares packages (evidence: `README.md`)
- Traveller → Auth screens: signs in (evidence: `README.md`)
- Auth screens → Auth client: uses client (evidence: `frontend/lib/auth-client.ts`)
- Auth client → Better Auth: authenticates (evidence: `README.md`)
- Session and roles → Auth client: reads session (evidence: `frontend/hooks/session.ts`)
- Package admin → Admin endpoints: manages packages (evidence: `README.md`)
- Admin endpoints → PostgreSQL data: reads and writes (evidence: `backend/controllers/admin.controller.ts`)
- Admin endpoints → Cloudinary: validates and deletes assets (evidence: `backend/controllers/admin.controller.ts`)
- Booking queue → Admin endpoints: manages bookings (evidence: `README.md`)
- Analytics dashboard → Analytics endpoints: requests reports (evidence: `README.md`)
- Analytics dashboard → Booking queue: loads popularity data (evidence: `frontend/app/(admin)/dashboard/page.tsx`)
- Image upload UI → Image endpoints: requests signature (evidence: `README.md`)
- Image endpoints → Cloudinary: signs and deletes (evidence: `backend/controllers/image.controller.ts`)
- Express API → Better Auth: mounts auth (evidence: `backend/server.ts`)
- Express API → Admin endpoints: mounts admin routes (evidence: `backend/server.ts`)
- Express API → Traveller endpoints: mounts user routes (evidence: `backend/server.ts`)
- Express API → Image endpoints: mounts image routes (evidence: `backend/server.ts`)
- Express API → Analytics endpoints: mounts analytics routes (evidence: `backend/server.ts`)