# uzicodes/northern-paribahan architecture

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

- Interactive diagram: https://gitdiagram.com/uzicodes/northern-paribahan
- Repository: https://github.com/uzicodes/northern-paribahan

## Overview

Northern Paribahan is a Bangladesh intercity bus reservation and fleet-operations product. The passenger journey searches dated departures, selects seats, pays, then receives or downloads a ticket; separate flows cover accounts, profiles, and ticket verification. Administrators manage buses, routes, bookings, and revenue, while a daily cron maintains the documented 31-day schedule window. The graph includes core UI, API, persistence, scheduling, and ticket-generation layers. Evidence is limited to the README and indexed or excerpted files; unsampled integrations and connections are omitted where their invocation is not shown.

Main entry points: [`src/lib/prisma.ts`](https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/prisma.ts) (Prisma database), [`src/actions/verifyTicket.ts`](https://github.com/uzicodes/northern-paribahan/blob/main/src/actions/verifyTicket.ts) (Ticket verification), [`src/utils/supabase/server.ts`](https://github.com/uzicodes/northern-paribahan/blob/main/src/utils/supabase/server.ts) (Server auth client), [`src/app/timetable/TimetableClient.tsx`](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/timetable/TimetableClient.tsx) (Departure search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_passenger["Passenger booking"]
  node_passenger["Passenger portal<br/>[page.tsx]"]
  node_timetable["Departure search"]
  node_dateutils["Date utilities<br/>[dateUtils.ts]"]
  node_schedules_api["Schedule search API<br/>[route.ts]"]
  node_seat_layout["Seat selection<br/>[SeatLayout.tsx]"]
  node_booking_api["Seat booking API<br/>[route.ts]"]
  node_checkout["Checkout<br/>[page.tsx]"]
  node_payment_init["Payment initiation<br/>[route.ts]"]
  node_payment_callback["Payment callback<br/>[route.ts]"]
  node_ticket_download["Ticket download<br/>[route.ts]"]
end

subgraph group_operations["Admin operations"]
  node_admin_console["Admin dashboard<br/>[page.tsx]"]
  node_fleet_admin["Fleet dashboard"]
  node_route_admin["Route dashboard"]
  node_admin_queries["Admin queries<br/>[admin-queries.ts]"]
end

subgraph group_scheduling["Schedule operations"]
  node_schedule_query["Schedule lookup<br/>[getSchedules.ts]"]
  node_cron["Daily schedule trigger<br/>[route.ts]"]
  node_generator["Schedule generator"]
end

subgraph group_identity["Identity and tickets"]
  node_auth_api["Account endpoints<br/>[route.ts]"]
  node_session_manager["Session manager<br/>[SessionManager.tsx]"]
  node_supabase_server["Server auth client<br/>[server.ts]"]
  node_profile_api["Profile and bookings<br/>[route.ts]"]
  node_verify_action["Ticket verification<br/>[verifyTicket.ts]"]
  node_pnr_modal["PNR verification UI"]
  node_ticket_types["Ticket data contract<br/>[ticket.ts]"]
end

subgraph group_platform["Data and delivery"]
  node_email_service["Ticket email service<br/>[index.ts]"]
  node_email_template["Email template<br/>[templates.ts]"]
  node_ticket_pdf["Ticket PDF renderer<br/>[ticketPdf.ts]"]
  node_pdf_theme["PDF theme<br/>[pdfTheme.ts]"]
  node_database[("Prisma database<br/>[prisma.ts]")]
end

node_payment_service["Payment provider"]
node_passenger_actor(("Passenger"))
node_scheduler_actor(("External scheduler"))
node_admin_actor(("Administrator"))

node_passenger_actor -->|"searches"| node_timetable
node_timetable -.->|"requests departures"| node_schedules_api
node_schedules_api -->|"delegates lookup"| node_schedule_query
node_schedules_api -->|"defaults date"| node_dateutils
node_timetable -->|"uses date rules"| node_dateutils
node_passenger_actor -->|"selects seats"| node_seat_layout
node_seat_layout -.->|"submits booking"| node_booking_api
node_booking_api -.->|"writes booking"| node_database
node_passenger_actor -->|"checks out"| node_checkout
node_checkout -.->|"starts payment"| node_payment_init
node_payment_init -->|"initiates payment"| node_payment_service
node_payment_service -->|"posts result"| node_payment_callback
node_payment_callback -->|"confirms booking"| node_database
node_payment_callback -->|"sends confirmation"| node_email_service
node_passenger_actor -->|"downloads ticket"| node_ticket_download
node_scheduler_actor -->|"triggers daily"| node_cron
node_cron -->|"generates schedules"| node_generator
node_generator -->|"inserts schedules"| node_database
node_admin_actor -->|"reviews operations"| node_admin_console
node_admin_actor -->|"manages fleet"| node_fleet_admin
node_admin_actor -->|"manages routes"| node_route_admin
node_admin_queries -->|"queries data"| node_database
node_session_manager -.->|"refreshes session"| node_supabase_server
node_auth_api -->|"authenticates"| node_supabase_server
node_profile_api -->|"checks identity"| node_supabase_server
node_profile_api -->|"reads profile"| node_database
node_pnr_modal -->|"requests verification"| node_verify_action
node_verify_action -->|"loads booking"| node_database
node_verify_action -->|"checks identity"| node_supabase_server
node_verify_action -->|"returns ticket data"| node_ticket_types
node_email_service -->|"generates attachment"| node_ticket_pdf
node_email_service -->|"renders message"| node_email_template
node_ticket_pdf -->|"uses theme"| node_pdf_theme

click node_passenger "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/page.tsx"
click node_timetable "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/timetable/TimetableClient.tsx"
click node_dateutils "https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/dateUtils.ts"
click node_schedules_api "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/schedules/route.ts"
click node_schedule_query "https://github.com/uzicodes/northern-paribahan/blob/main/src/actions/getSchedules.ts"
click node_seat_layout "https://github.com/uzicodes/northern-paribahan/blob/main/src/components/SeatLayout.tsx"
click node_booking_api "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/buses/%5Bid%5D/book/route.ts"
click node_checkout "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/checkout/page.tsx"
click node_payment_init "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/payment/init/route.ts"
click node_payment_callback "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/payment/callback/route.ts"
click node_ticket_download "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/ticket/download/route.ts"
click node_admin_console "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/admin/page.tsx"
click node_fleet_admin "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/admin/buses/AdminBusesClient.tsx"
click node_route_admin "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/admin/routes/AdminRoutesClient.tsx"
click node_admin_queries "https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/admin-queries.ts"
click node_cron "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/cron/generate-daily-schedules/route.ts"
click node_generator "https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/scheduleGenerator.ts"
click node_auth_api "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/auth/register/route.ts"
click node_session_manager "https://github.com/uzicodes/northern-paribahan/blob/main/src/components/SessionManager.tsx"
click node_supabase_server "https://github.com/uzicodes/northern-paribahan/blob/main/src/utils/supabase/server.ts"
click node_profile_api "https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/user/profile/route.ts"
click node_verify_action "https://github.com/uzicodes/northern-paribahan/blob/main/src/actions/verifyTicket.ts"
click node_pnr_modal "https://github.com/uzicodes/northern-paribahan/blob/main/src/components/ticket/PnrVerificationModal.tsx"
click node_ticket_types "https://github.com/uzicodes/northern-paribahan/blob/main/src/types/ticket.ts"
click node_email_service "https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/email/index.ts"
click node_email_template "https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/email/templates.ts"
click node_ticket_pdf "https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/email/ticketPdf.ts"
click node_pdf_theme "https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/email/pdfTheme.ts"
click node_database "https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/prisma.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_passenger,node_timetable,node_dateutils,node_schedules_api,node_seat_layout,node_booking_api,node_checkout,node_payment_init,node_payment_callback,node_ticket_download toneBlue
class node_admin_console,node_fleet_admin,node_route_admin,node_admin_queries toneAmber
class node_schedule_query,node_cron,node_generator toneMint
class node_auth_api,node_session_manager,node_supabase_server,node_profile_api,node_verify_action,node_pnr_modal,node_ticket_types,node_scheduler_actor toneRose
class node_email_service,node_email_template,node_ticket_pdf,node_pdf_theme,node_database,node_payment_service,node_passenger_actor,node_admin_actor toneIndigo
```

## Components

### Passenger booking

- [Passenger portal](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Departure search](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/timetable/TimetableClient.tsx): `src/app/timetable/TimetableClient.tsx`
- [Date utilities](https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/dateUtils.ts): `src/lib/dateUtils.ts`
- [Schedule search API](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/schedules/route.ts): `src/app/api/schedules/route.ts`
- [Seat selection](https://github.com/uzicodes/northern-paribahan/blob/main/src/components/SeatLayout.tsx): `src/components/SeatLayout.tsx`
- [Seat booking API](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/buses/%5Bid%5D/book/route.ts): `src/app/api/buses/[id]/book/route.ts`
- [Checkout](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/checkout/page.tsx): `src/app/checkout/page.tsx`
- [Payment initiation](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/payment/init/route.ts): `src/app/api/payment/init/route.ts`
- [Payment callback](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/payment/callback/route.ts): `src/app/api/payment/callback/route.ts`
- [Ticket download](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/ticket/download/route.ts): `src/app/api/ticket/download/route.ts`

### Admin operations

- [Admin dashboard](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/admin/page.tsx): `src/app/admin/page.tsx`
- [Fleet dashboard](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/admin/buses/AdminBusesClient.tsx): `src/app/admin/buses/AdminBusesClient.tsx`
- [Route dashboard](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/admin/routes/AdminRoutesClient.tsx): `src/app/admin/routes/AdminRoutesClient.tsx`
- [Admin queries](https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/admin-queries.ts): `src/lib/admin-queries.ts`

### Schedule operations

- [Schedule lookup](https://github.com/uzicodes/northern-paribahan/blob/main/src/actions/getSchedules.ts): `src/actions/getSchedules.ts`
- [Daily schedule trigger](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/cron/generate-daily-schedules/route.ts): `src/app/api/cron/generate-daily-schedules/route.ts`
- [Schedule generator](https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/scheduleGenerator.ts): `src/lib/scheduleGenerator.ts`

### Identity and tickets

- [Account endpoints](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/auth/register/route.ts): `src/app/api/auth/register/route.ts`
- [Session manager](https://github.com/uzicodes/northern-paribahan/blob/main/src/components/SessionManager.tsx): `src/components/SessionManager.tsx`
- [Server auth client](https://github.com/uzicodes/northern-paribahan/blob/main/src/utils/supabase/server.ts): `src/utils/supabase/server.ts`
- [Profile and bookings](https://github.com/uzicodes/northern-paribahan/blob/main/src/app/api/user/profile/route.ts): `src/app/api/user/profile/route.ts`
- [Ticket verification](https://github.com/uzicodes/northern-paribahan/blob/main/src/actions/verifyTicket.ts): `src/actions/verifyTicket.ts`
- [PNR verification UI](https://github.com/uzicodes/northern-paribahan/blob/main/src/components/ticket/PnrVerificationModal.tsx): `src/components/ticket/PnrVerificationModal.tsx`
- [Ticket data contract](https://github.com/uzicodes/northern-paribahan/blob/main/src/types/ticket.ts): `src/types/ticket.ts`

### Data and delivery

- [Ticket email service](https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/email/index.ts): `src/lib/email/index.ts`
- [Email template](https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/email/templates.ts): `src/lib/email/templates.ts`
- [Ticket PDF renderer](https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/email/ticketPdf.ts): `src/lib/email/ticketPdf.ts`
- [PDF theme](https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/email/pdfTheme.ts): `src/lib/email/pdfTheme.ts`
- [Prisma database](https://github.com/uzicodes/northern-paribahan/blob/main/src/lib/prisma.ts): `src/lib/prisma.ts`

### Other components

- **Payment provider**
- **Passenger**
- **External scheduler**
- **Administrator**

## Connections

- Passenger → Departure search: searches
- Departure search → Schedule search API: requests departures
- Schedule search API → Schedule lookup: delegates lookup (evidence: `src/app/api/schedules/route.ts`)
- Schedule search API → Date utilities: defaults date (evidence: `src/app/api/schedules/route.ts`)
- Departure search → Date utilities: uses date rules (evidence: `src/app/timetable/TimetableClient.tsx`)
- Passenger → Seat selection: selects seats
- Seat selection → Seat booking API: submits booking
- Seat booking API → Prisma database: writes booking
- Passenger → Checkout: checks out
- Checkout → Payment initiation: starts payment
- Payment initiation → Payment provider: initiates payment
- Payment provider → Payment callback: posts result
- Payment callback → Prisma database: confirms booking (evidence: `src/app/api/payment/callback/route.ts`)
- Payment callback → Ticket email service: sends confirmation (evidence: `src/app/api/payment/callback/route.ts`)
- Passenger → Ticket download: downloads ticket
- External scheduler → Daily schedule trigger: triggers daily
- Daily schedule trigger → Schedule generator: generates schedules (evidence: `src/app/api/cron/generate-daily-schedules/route.ts`)
- Schedule generator → Prisma database: inserts schedules (evidence: `src/lib/scheduleGenerator.ts`)
- Administrator → Admin dashboard: reviews operations
- Administrator → Fleet dashboard: manages fleet
- Administrator → Route dashboard: manages routes
- Admin queries → Prisma database: queries data (evidence: `src/lib/admin-queries.ts`)
- Session manager → Server auth client: refreshes session
- Account endpoints → Server auth client: authenticates (evidence: `src/app/api/auth/register/route.ts`)
- Profile and bookings → Server auth client: checks identity (evidence: `src/app/api/user/profile/route.ts`)
- Profile and bookings → Prisma database: reads profile (evidence: `src/app/api/user/profile/route.ts`)
- PNR verification UI → Ticket verification: requests verification (evidence: `src/components/ticket/PnrVerificationModal.tsx`)
- Ticket verification → Prisma database: loads booking (evidence: `src/actions/verifyTicket.ts`)
- Ticket verification → Server auth client: checks identity (evidence: `src/actions/verifyTicket.ts`)
- Ticket verification → Ticket data contract: returns ticket data (evidence: `src/actions/verifyTicket.ts`)
- Ticket email service → Ticket PDF renderer: generates attachment (evidence: `src/lib/email/index.ts`)
- Ticket email service → Email template: renders message (evidence: `src/lib/email/index.ts`)
- Ticket PDF renderer → PDF theme: uses theme (evidence: `src/lib/email/ticketPdf.ts`)
