# actualacademie/holbietrips architecture

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

- Interactive diagram: https://gitdiagram.com/actualacademie/holbietrips
- Repository: https://github.com/actualacademie/holbietrips

## Overview

HolbieTrips is a local travel-booking and OWASP security-training lab. The main user flow runs from the browser through the local gateway to the React app, then through the API for discovery, authentication, booking, payment, profile, or support operations. PostgreSQL holds business and audit state; payment and mail are local simulators. The API composition root registers the route modules, while the React composition root coordinates feature hooks and screens. The README documents the service topology and capabilities; some route and simulator internals were not excerpted, so those connections are cited only where documented.

Main entry points: [`apps/api/src/app.ts`](https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/app.ts) (Fastify API), [`apps/web/src/App.tsx`](https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/App.tsx) (React app), [`apps/web/src/api.ts`](https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/api.ts) (API client), [`apps/api/src/routes/auth.ts`](https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/auth.ts) (Accounts and reset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser application"]
  node_app["React app<br/>[App.tsx]"]
  node_session["Session state<br/>[useSession.ts]"]
  node_traveldata["Travel data<br/>[useTravelData.ts]"]
  node_bookingflow["Booking workflow"]
  node_discovery["Catalogue screen<br/>[DiscoverPage.tsx]"]
  node_bookingui["Booking screens<br/>[BookingsPage.tsx]"]
  node_profileui["Profile screen<br/>[ProfilePage.tsx]"]
  node_supportui["Support screen<br/>[SupportPage.tsx]"]
  node_auditui["Audit screen<br/>[AuditPage.tsx]"]
  node_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and business"]
  node_api["Fastify API<br/>[app.ts]"]
  node_auth["Accounts and reset<br/>[auth.ts]"]
  node_catalog["Trip catalogue<br/>[catalog.ts]"]
  node_bookings["Booking lifecycle<br/>[bookings.ts]"]
  node_payments["Checkout<br/>[payments.ts]"]
  node_profile["Traveller profile<br/>[profile.ts]"]
  node_support["Tickets and audit<br/>[support.ts]"]
  node_system["Health operations<br/>[system.ts]"]
  node_security["Security helpers<br/>[security.ts]"]
  node_flags["Challenge flags<br/>[challenge-flags.ts]"]
end

subgraph group_runtime["Local runtime"]
  node_gateway["Local gateway<br/>[server.ts]"]
  node_paymentservice["Payment simulator<br/>[server.ts]"]
  node_mailservice["Mail simulator<br/>[server.ts]"]
end

subgraph group_state["Persistence"]
  node_postgres[("PostgreSQL")]
end

node_browser(("Traveller"))

node_browser -->|"requests app"| node_gateway
node_gateway -->|"proxies traffic"| node_api
node_api -->|"serves frontend"| node_app
node_app -->|"restores session"| node_session
node_session -->|"validates session"| node_client
node_app -->|"loads travel data"| node_traveldata
node_app -->|"coordinates booking"| node_bookingflow
node_app -->|"renders discovery"| node_discovery
node_app -->|"renders bookings"| node_bookingui
node_app -->|"renders profile"| node_profileui
node_app -->|"renders support"| node_supportui
node_app -->|"renders audit"| node_auditui
node_traveldata -->|"requests data"| node_client
node_bookingflow -->|"runs actions"| node_client
node_profileui -->|"updates profile"| node_client
node_supportui -->|"manages tickets"| node_client
node_client -->|"sends API requests"| node_api
node_api -->|"registers routes"| node_auth
node_api -->|"registers routes"| node_catalog
node_api -->|"registers routes"| node_bookings
node_api -->|"registers routes"| node_payments
node_api -->|"registers routes"| node_profile
node_api -->|"registers routes"| node_support
node_api -->|"registers routes"| node_system
node_auth -->|"reads and writes"| node_postgres
node_bookings -->|"reads and writes"| node_postgres
node_payments -.->|"records checkout"| node_postgres
node_profile -.->|"stores traveller data"| node_postgres
node_support -.->|"stores tickets and audit"| node_postgres
node_api -->|"uses connection pool"| node_postgres
node_auth -->|"sends reset message"| node_mailservice
node_payments -.->|"requests payment outcome"| node_paymentservice
node_auth -->|"uses token helpers"| node_security
node_bookings -->|"uses security helpers"| node_security
node_payments -->|"uses signature helpers"| node_security
node_api -->|"creates flag provider"| node_flags
node_auth -->|"returns challenge flag"| node_flags

click node_gateway "https://github.com/actualacademie/holbietrips/blob/main/services/local-gateway/src/server.ts"
click node_app "https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/App.tsx"
click node_session "https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/hooks/useSession.ts"
click node_traveldata "https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/hooks/useTravelData.ts"
click node_bookingflow "https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/hooks/useBookingWorkflow.ts"
click node_discovery "https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/pages/DiscoverPage.tsx"
click node_bookingui "https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/pages/BookingsPage.tsx"
click node_profileui "https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/pages/ProfilePage.tsx"
click node_supportui "https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/pages/SupportPage.tsx"
click node_auditui "https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/pages/AuditPage.tsx"
click node_client "https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/api.ts"
click node_api "https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/app.ts"
click node_auth "https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/auth.ts"
click node_catalog "https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/catalog.ts"
click node_bookings "https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/bookings.ts"
click node_payments "https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/payments.ts"
click node_profile "https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/profile.ts"
click node_support "https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/support.ts"
click node_system "https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/system.ts"
click node_security "https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/security.ts"
click node_flags "https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/challenge-flags.ts"
click node_paymentservice "https://github.com/actualacademie/holbietrips/blob/main/services/fake-payment/src/server.ts"
click node_mailservice "https://github.com/actualacademie/holbietrips/blob/main/services/fake-mail/src/server.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_app,node_session,node_traveldata,node_bookingflow,node_discovery,node_bookingui,node_profileui,node_supportui,node_auditui,node_client toneBlue
class node_api,node_auth,node_catalog,node_bookings,node_payments,node_profile,node_support,node_system,node_security,node_flags toneAmber
class node_gateway,node_paymentservice,node_mailservice toneMint
class node_postgres toneRose
class node_browser toneIndigo
```

## Components

### Browser application

- [React app](https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Session state](https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/hooks/useSession.ts): `apps/web/src/hooks/useSession.ts`
- [Travel data](https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/hooks/useTravelData.ts): `apps/web/src/hooks/useTravelData.ts`
- [Booking workflow](https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/hooks/useBookingWorkflow.ts): `apps/web/src/hooks/useBookingWorkflow.ts`
- [Catalogue screen](https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/pages/DiscoverPage.tsx): `apps/web/src/pages/DiscoverPage.tsx`
- [Booking screens](https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/pages/BookingsPage.tsx): `apps/web/src/pages/BookingsPage.tsx`
- [Profile screen](https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/pages/ProfilePage.tsx): `apps/web/src/pages/ProfilePage.tsx`
- [Support screen](https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/pages/SupportPage.tsx): `apps/web/src/pages/SupportPage.tsx`
- [Audit screen](https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/pages/AuditPage.tsx): `apps/web/src/pages/AuditPage.tsx`
- [API client](https://github.com/actualacademie/holbietrips/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`

### API and business

- [Fastify API](https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Accounts and reset](https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/auth.ts): `apps/api/src/routes/auth.ts`
- [Trip catalogue](https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/catalog.ts): `apps/api/src/routes/catalog.ts`
- [Booking lifecycle](https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/bookings.ts): `apps/api/src/routes/bookings.ts`
- [Checkout](https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/payments.ts): `apps/api/src/routes/payments.ts`
- [Traveller profile](https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/profile.ts): `apps/api/src/routes/profile.ts`
- [Tickets and audit](https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/support.ts): `apps/api/src/routes/support.ts`
- [Health operations](https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/routes/system.ts): `apps/api/src/routes/system.ts`
- [Security helpers](https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/security.ts): `apps/api/src/security.ts`
- [Challenge flags](https://github.com/actualacademie/holbietrips/blob/main/apps/api/src/challenge-flags.ts): `apps/api/src/challenge-flags.ts`

### Local runtime

- [Local gateway](https://github.com/actualacademie/holbietrips/blob/main/services/local-gateway/src/server.ts): `services/local-gateway/src/server.ts`
- [Payment simulator](https://github.com/actualacademie/holbietrips/blob/main/services/fake-payment/src/server.ts): `services/fake-payment/src/server.ts`
- [Mail simulator](https://github.com/actualacademie/holbietrips/blob/main/services/fake-mail/src/server.ts): `services/fake-mail/src/server.ts`

### Persistence

- **PostgreSQL**

### Other components

- **Traveller**

## Connections

- Traveller → Local gateway: requests app
- Local gateway → Fastify API: proxies traffic
- Fastify API → React app: serves frontend (evidence: `apps/api/src/app.ts`)
- React app → Session state: restores session (evidence: `apps/web/src/App.tsx`)
- Session state → API client: validates session (evidence: `apps/web/src/hooks/useSession.ts`)
- React app → Travel data: loads travel data (evidence: `apps/web/src/App.tsx`)
- React app → Booking workflow: coordinates booking (evidence: `apps/web/src/App.tsx`)
- React app → Catalogue screen: renders discovery (evidence: `apps/web/src/App.tsx`)
- React app → Booking screens: renders bookings (evidence: `apps/web/src/App.tsx`)
- React app → Profile screen: renders profile (evidence: `apps/web/src/App.tsx`)
- React app → Support screen: renders support (evidence: `apps/web/src/App.tsx`)
- React app → Audit screen: renders audit (evidence: `apps/web/src/App.tsx`)
- Travel data → API client: requests data (evidence: `apps/web/src/hooks/useTravelData.ts`)
- Booking workflow → API client: runs actions (evidence: `apps/web/src/hooks/useBookingWorkflow.ts`)
- Profile screen → API client: updates profile (evidence: `apps/web/src/pages/ProfilePage.tsx`)
- Support screen → API client: manages tickets (evidence: `apps/web/src/pages/SupportPage.tsx`)
- API client → Fastify API: sends API requests
- Fastify API → Accounts and reset: registers routes (evidence: `apps/api/src/app.ts`)
- Fastify API → Trip catalogue: registers routes (evidence: `apps/api/src/app.ts`)
- Fastify API → Booking lifecycle: registers routes (evidence: `apps/api/src/app.ts`)
- Fastify API → Checkout: registers routes (evidence: `apps/api/src/app.ts`)
- Fastify API → Traveller profile: registers routes (evidence: `apps/api/src/app.ts`)
- Fastify API → Tickets and audit: registers routes (evidence: `apps/api/src/app.ts`)
- Fastify API → Health operations: registers routes (evidence: `apps/api/src/app.ts`)
- Accounts and reset → PostgreSQL: reads and writes (evidence: `apps/api/src/routes/auth.ts`)
- Booking lifecycle → PostgreSQL: reads and writes (evidence: `apps/api/src/routes/bookings.ts`)
- Checkout → PostgreSQL: records checkout
- Traveller profile → PostgreSQL: stores traveller data
- Tickets and audit → PostgreSQL: stores tickets and audit
- Fastify API → PostgreSQL: uses connection pool (evidence: `apps/api/src/app.ts`)
- Accounts and reset → Mail simulator: sends reset message (evidence: `apps/api/src/routes/auth.ts`)
- Checkout → Payment simulator: requests payment outcome
- Accounts and reset → Security helpers: uses token helpers (evidence: `apps/api/src/routes/auth.ts`)
- Booking lifecycle → Security helpers: uses security helpers (evidence: `apps/api/src/routes/bookings.ts`)
- Checkout → Security helpers: uses signature helpers (evidence: `apps/api/src/routes/payments.ts`)
- Fastify API → Challenge flags: creates flag provider (evidence: `apps/api/src/app.ts`)
- Accounts and reset → Challenge flags: returns challenge flag (evidence: `apps/api/src/routes/auth.ts`)
