# itmangz/bussin architecture

> Architecture diagram of the GitHub repository itmangz/bussin, 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/itmangz/bussin
- Repository: https://github.com/itmangz/bussin

## Overview

BUSSIN is a commuter booking and queue-management product, delivered here as a Swing desktop client and a Spring API. The main user path is desktop startup and authentication, trip discovery, seat/booking review and confirmation; staff also manage routes, buses, trips, users, queues and reports. The API exposes bus, route, trip and user management backed by repositories. The README also describes payments, voice announcements and Gmail verification, but the supplied tree and excerpts do not establish their runtime implementations or wiring, so those are not represented as implemented components.

Main entry points: [`bussin-desktop/src/main/java/com/bussin/desktop/App.java`](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/App.java) (Desktop startup), [`src/main/java/com/bussin/bussin_api/service/TripService.java`](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/service/TripService.java) (Trip service), [`bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/BookingScreen.java`](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/BookingScreen.java) (Trip and seat booking), [`bussin-desktop/src/main/java/com/bussin/desktop/services/BookingService.java`](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/services/BookingService.java) (Booking service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop client"]
  node_app["Desktop startup<br/>[App.java]"]
  node_authui["Login and registration"]
  node_authsession["Auth session<br/>[AuthSession.java]"]
  node_mainframe["Application navigation<br/>[MainFrame.java]"]
  node_adminui["Operations screens"]
  node_queueui["Queue management<br/>[QueueScreen.java]"]
  node_reports["Reports and export<br/>[ReportScreen.java]"]
  node_userapi["User API client"]
  node_apiclient["HTTP client<br/>[ApiClient.java]"]
end

subgraph group_booking["Commuter booking"]
  node_bookingui["Trip and seat booking<br/>[BookingScreen.java]"]
  node_bookingstate["Booking state<br/>[BookingStore.java]"]
  node_bookingreview["Booking review"]
  node_bookingconfirm["Booking confirmation"]
  node_bookingservice["Booking service"]
  node_tripsearch["Trip search"]
end

subgraph group_api["API services"]
  node_routecontroller["Route endpoints"]
  node_tripcontroller["Trip endpoints"]
  node_usercontroller["User endpoints"]
  node_buscontroller["Bus endpoints<br/>[BusController.java]"]
  node_routeservice["Route service<br/>[RouteService.java]"]
  node_tripservice["Trip service<br/>[TripService.java]"]
  node_userservice["User service<br/>[UserService.java]"]
  node_busservice["Bus service<br/>[BusService.java]"]
end

subgraph group_data["Persistent domain"]
  node_routeentity[("Routes<br/>[Route.java]")]
  node_tripentity[("Trips<br/>[Trip.java]")]
  node_busentity[("Buses<br/>[Bus.java]")]
  node_triprepo["Trip repository"]
  node_userrepo["User repository"]
  node_routerepo["Route repository"]
  node_busrepo["Bus repository<br/>[BusRepository.java]"]
end

node_commuter(("Commuter"))
node_staff(("Staff user"))

node_commuter -.->|"starts"| node_app
node_staff -.->|"starts"| node_app
node_app -->|"opens"| node_authui
node_app -->|"uses"| node_authsession
node_app -->|"opens"| node_mainframe
node_mainframe -.->|"navigates"| node_bookingui
node_commuter -.->|"searches trips"| node_tripsearch
node_tripsearch -.->|"selects trip"| node_bookingui
node_bookingui -.->|"updates"| node_bookingstate
node_bookingui -.->|"opens review"| node_bookingreview
node_bookingreview -->|"confirms"| node_bookingconfirm
node_bookingconfirm -.->|"creates booking"| node_bookingservice
node_bookingservice -->|"uses"| node_bookingstate
node_bookingservice -.->|"reads trips"| node_tripsearch
node_staff -.->|"manages operations"| node_adminui
node_staff -.->|"monitors queue"| node_queueui
node_staff -.->|"views reports"| node_reports
node_userapi -->|"uses"| node_apiclient
node_userapi -.->|"HTTP requests"| node_usercontroller
node_routecontroller -->|"delegates"| node_routeservice
node_tripcontroller -->|"delegates"| node_tripservice
node_usercontroller -->|"delegates"| node_userservice
node_buscontroller -.->|"delegates"| node_busservice
node_routeservice -->|"reads and writes"| node_routerepo
node_tripservice -->|"reads and writes"| node_triprepo
node_tripservice -->|"looks up buses"| node_busrepo
node_tripservice -->|"looks up routes"| node_routerepo
node_userservice -->|"reads and writes"| node_userrepo
node_busservice -->|"reads and writes"| node_busrepo
node_triprepo -->|"persists"| node_tripentity

click node_app "https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/App.java"
click node_authui "https://github.com/itmangz/bussin/tree/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/auth"
click node_authsession "https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/services/AuthSession.java"
click node_mainframe "https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/MainFrame.java"
click node_bookingui "https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/BookingScreen.java"
click node_bookingstate "https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/flow/BookingStore.java"
click node_bookingreview "https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/BookingReviewScreen.java"
click node_bookingconfirm "https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/BookingConfirmationScreen.java"
click node_bookingservice "https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/services/BookingService.java"
click node_tripsearch "https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/TripSearchScreen.java"
click node_adminui "https://github.com/itmangz/bussin/tree/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens"
click node_queueui "https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/QueueScreen.java"
click node_reports "https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/ReportScreen.java"
click node_userapi "https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/services/UserApiService.java"
click node_apiclient "https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/services/ApiClient.java"
click node_routecontroller "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/controller/RouteController.java"
click node_tripcontroller "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/controller/TripController.java"
click node_usercontroller "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/controller/UserController.java"
click node_buscontroller "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/controller/BusController.java"
click node_routeservice "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/service/RouteService.java"
click node_tripservice "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/service/TripService.java"
click node_userservice "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/service/UserService.java"
click node_busservice "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/service/BusService.java"
click node_routeentity "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/entity/Route.java"
click node_tripentity "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/entity/Trip.java"
click node_busentity "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/entity/Bus.java"
click node_triprepo "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/repository/TripRepository.java"
click node_userrepo "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/repository/UserRepository.java"
click node_routerepo "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/repository/RouteRepository.java"
click node_busrepo "https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/repository/BusRepository.java"

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_app,node_authui,node_authsession,node_mainframe,node_adminui,node_queueui,node_reports,node_userapi,node_apiclient,node_staff toneBlue
class node_bookingui,node_bookingstate,node_bookingreview,node_bookingconfirm,node_bookingservice,node_tripsearch toneAmber
class node_routecontroller,node_tripcontroller,node_usercontroller,node_buscontroller,node_routeservice,node_tripservice,node_userservice,node_busservice toneMint
class node_routeentity,node_tripentity,node_busentity,node_triprepo,node_userrepo,node_routerepo,node_busrepo toneRose
class node_commuter toneIndigo
```

## Components

### Desktop client

- [Desktop startup](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/App.java): `bussin-desktop/src/main/java/com/bussin/desktop/App.java`
- [Login and registration](https://github.com/itmangz/bussin/tree/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/auth): `bussin-desktop/src/main/java/com/bussin/desktop/ui/auth`
- [Auth session](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/services/AuthSession.java): `bussin-desktop/src/main/java/com/bussin/desktop/services/AuthSession.java`
- [Application navigation](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/MainFrame.java): `bussin-desktop/src/main/java/com/bussin/desktop/ui/MainFrame.java`
- [Operations screens](https://github.com/itmangz/bussin/tree/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens): `bussin-desktop/src/main/java/com/bussin/desktop/ui/screens`
- [Queue management](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/QueueScreen.java): `bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/QueueScreen.java`
- [Reports and export](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/ReportScreen.java): `bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/ReportScreen.java`
- [User API client](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/services/UserApiService.java): `bussin-desktop/src/main/java/com/bussin/desktop/services/UserApiService.java`
- [HTTP client](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/services/ApiClient.java): `bussin-desktop/src/main/java/com/bussin/desktop/services/ApiClient.java`

### Commuter booking

- [Trip and seat booking](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/BookingScreen.java): `bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/BookingScreen.java`
- [Booking state](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/flow/BookingStore.java): `bussin-desktop/src/main/java/com/bussin/desktop/ui/flow/BookingStore.java`
- [Booking review](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/BookingReviewScreen.java): `bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/BookingReviewScreen.java`
- [Booking confirmation](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/BookingConfirmationScreen.java): `bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/BookingConfirmationScreen.java`
- [Booking service](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/services/BookingService.java): `bussin-desktop/src/main/java/com/bussin/desktop/services/BookingService.java`
- [Trip search](https://github.com/itmangz/bussin/blob/main/bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/TripSearchScreen.java): `bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/TripSearchScreen.java`

### API services

- [Route endpoints](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/controller/RouteController.java): `src/main/java/com/bussin/bussin_api/controller/RouteController.java`
- [Trip endpoints](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/controller/TripController.java): `src/main/java/com/bussin/bussin_api/controller/TripController.java`
- [User endpoints](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/controller/UserController.java): `src/main/java/com/bussin/bussin_api/controller/UserController.java`
- [Bus endpoints](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/controller/BusController.java): `src/main/java/com/bussin/bussin_api/controller/BusController.java`
- [Route service](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/service/RouteService.java): `src/main/java/com/bussin/bussin_api/service/RouteService.java`
- [Trip service](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/service/TripService.java): `src/main/java/com/bussin/bussin_api/service/TripService.java`
- [User service](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/service/UserService.java): `src/main/java/com/bussin/bussin_api/service/UserService.java`
- [Bus service](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/service/BusService.java): `src/main/java/com/bussin/bussin_api/service/BusService.java`

### Persistent domain

- [Routes](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/entity/Route.java): `src/main/java/com/bussin/bussin_api/entity/Route.java`
- [Trips](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/entity/Trip.java): `src/main/java/com/bussin/bussin_api/entity/Trip.java`
- [Buses](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/entity/Bus.java): `src/main/java/com/bussin/bussin_api/entity/Bus.java`
- [Trip repository](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/repository/TripRepository.java): `src/main/java/com/bussin/bussin_api/repository/TripRepository.java`
- [User repository](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/repository/UserRepository.java): `src/main/java/com/bussin/bussin_api/repository/UserRepository.java`
- [Route repository](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/repository/RouteRepository.java): `src/main/java/com/bussin/bussin_api/repository/RouteRepository.java`
- [Bus repository](https://github.com/itmangz/bussin/blob/main/src/main/java/com/bussin/bussin_api/repository/BusRepository.java): `src/main/java/com/bussin/bussin_api/repository/BusRepository.java`

### Other components

- **Commuter**
- **Staff user**

## Connections

- Commuter → Desktop startup: starts
- Staff user → Desktop startup: starts
- Desktop startup → Login and registration: opens (evidence: `bussin-desktop/src/main/java/com/bussin/desktop/App.java`)
- Desktop startup → Auth session: uses (evidence: `bussin-desktop/src/main/java/com/bussin/desktop/App.java`)
- Desktop startup → Application navigation: opens (evidence: `bussin-desktop/src/main/java/com/bussin/desktop/App.java`)
- Application navigation → Trip and seat booking: navigates (evidence: `bussin-desktop/src/main/java/com/bussin/desktop/ui/MainFrame.java`)
- Commuter → Trip search: searches trips
- Trip search → Trip and seat booking: selects trip
- Trip and seat booking → Booking state: updates
- Trip and seat booking → Booking review: opens review
- Booking review → Booking confirmation: confirms (evidence: `bussin-desktop/src/main/java/com/bussin/desktop/ui/screens/BookingReviewScreen.java`)
- Booking confirmation → Booking service: creates booking
- Booking service → Booking state: uses (evidence: `bussin-desktop/src/main/java/com/bussin/desktop/services/BookingService.java`)
- Booking service → Trip search: reads trips
- Staff user → Operations screens: manages operations
- Staff user → Queue management: monitors queue
- Staff user → Reports and export: views reports
- User API client → HTTP client: uses (evidence: `bussin-desktop/src/main/java/com/bussin/desktop/services/UserApiService.java`)
- User API client → User endpoints: HTTP requests
- Route endpoints → Route service: delegates (evidence: `src/main/java/com/bussin/bussin_api/controller/RouteController.java`)
- Trip endpoints → Trip service: delegates (evidence: `src/main/java/com/bussin/bussin_api/controller/TripController.java`)
- User endpoints → User service: delegates (evidence: `src/main/java/com/bussin/bussin_api/controller/UserController.java`)
- Bus endpoints → Bus service: delegates (evidence: `src/main/java/com/bussin/bussin_api/controller/BusController.java`)
- Route service → Route repository: reads and writes (evidence: `src/main/java/com/bussin/bussin_api/service/RouteService.java`)
- Trip service → Trip repository: reads and writes (evidence: `src/main/java/com/bussin/bussin_api/service/TripService.java`)
- Trip service → Bus repository: looks up buses (evidence: `src/main/java/com/bussin/bussin_api/service/TripService.java`)
- Trip service → Route repository: looks up routes (evidence: `src/main/java/com/bussin/bussin_api/service/TripService.java`)
- User service → User repository: reads and writes (evidence: `src/main/java/com/bussin/bussin_api/service/UserService.java`)
- Bus service → Bus repository: reads and writes (evidence: `src/main/java/com/bussin/bussin_api/service/BusService.java`)
- Trip repository → Trips: persists (evidence: `src/main/java/com/bussin/bussin_api/repository/TripRepository.java`)
