# atcasanova/trips architecture

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

## Overview

Trips is a collaborative travel-planning product: users create or join a trip, build an itinerary and reservations, add documents and expenses, then share or export an editorial Trip Book. The React client calls an Express API backed by PostgreSQL; backend services add AI extraction, location resolution, email intake and PDF generation. The graph preserves README-documented capabilities where their implementation was not sampled; those links are documented rather than claims of inspected call sites.

Main entry points: [`server/src/db/pool.ts`](https://github.com/atcasanova/trips/blob/main/server/src/db/pool.ts) (PostgreSQL), [`server/src/routes/index.ts`](https://github.com/atcasanova/trips/blob/main/server/src/routes/index.ts) (REST routing), [`server/src/controllers/tripController.ts`](https://github.com/atcasanova/trips/blob/main/server/src/controllers/tripController.ts) (Trip and membership), [`server/src/controllers/itineraryController.ts`](https://github.com/atcasanova/trips/blob/main/server/src/controllers/itineraryController.ts) (Itinerary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_spa["Trip workspace<br/>[TripDetailPage.tsx]"]
  node_dashboard["Trip dashboard<br/>[DashboardPage.tsx]"]
  node_clientapi["API client<br/>[client.ts]"]
end

subgraph group_api["API and access"]
  node_auth["Authentication<br/>[authController.ts]"]
  node_routes["REST routing<br/>[index.ts]"]
  node_middleware["Session access<br/>[auth.ts]"]
  node_admin["Administration<br/>[adminController.ts]"]
end

subgraph group_planning["Trip planning"]
  node_trip["Trip and membership<br/>[tripController.ts]"]
  node_itinerary["Itinerary"]
  node_location["Location resolution"]
  node_reservations["Reservations"]
  node_expenses["Expense splitting"]
end

subgraph group_documents["Documents and publishing"]
  node_documents["Document management"]
  node_confirmation["Document confirmation"]
  node_ai["AI extraction<br/>[openaiService.ts]"]
  node_emailintake["Inbound email"]
  node_reports["Trip Book content<br/>[reportService.ts]"]
  node_pdf["PDF rendering"]
end

subgraph group_platform["Persistence and integrations"]
  node_db[("PostgreSQL<br/>[pool.ts]")]
  node_openai{{"OpenAI"}}
  node_smtp{{"SMTP mail"}}
  node_pexels{{"Pexels photos"}}
  node_pdfservice["PDF service<br/>[pdfService.ts]"]
end

node_traveler(("Traveler"))

node_traveler -->|"plans trips"| node_dashboard
node_dashboard -.->|"requests data"| node_clientapi
node_spa -.->|"requests trip data"| node_clientapi
node_clientapi -->|"calls REST API"| node_routes
node_routes -->|"routes authentication"| node_auth
node_routes -->|"routes trip requests"| node_trip
node_routes -->|"routes itinerary requests"| node_itinerary
node_routes -->|"routes reservations"| node_reservations
node_routes -->|"routes expenses"| node_expenses
node_routes -->|"routes documents"| node_documents
node_routes -->|"routes admin requests"| node_admin
node_middleware -->|"checks sessions"| node_db
node_trip -->|"reads and writes"| node_db
node_trip -->|"resolves locations"| node_location
node_itinerary -->|"reads and writes"| node_db
node_itinerary -->|"refreshes locations"| node_location
node_itinerary -->|"requests regeneration"| node_pdf
node_location -->|"queries trip data"| node_db
node_location -.->|"resolves places"| node_openai
node_reservations -->|"reads and writes"| node_db
node_expenses -->|"reads and writes"| node_db
node_documents -.->|"confirms extraction"| node_confirmation
node_confirmation -->|"extracts document"| node_ai
node_confirmation -->|"stores confirmations"| node_db
node_ai -->|"extracts structured data"| node_openai
node_ai -->|"records AI audit"| node_db
node_emailintake -->|"analyzes attachments"| node_ai
node_emailintake -->|"confirms documents"| node_confirmation
node_emailintake -.->|"sends notifications"| node_smtp
node_reports -->|"loads trip data"| node_db
node_pdf -->|"builds report HTML"| node_reports
node_pdf -->|"renders PDF"| node_pdfservice
node_pdf -->|"stores PDF metadata"| node_db
node_admin -->|"queries metrics"| node_db
node_admin -.->|"sends invitations"| node_smtp
node_trip -->|"sends trip invitations"| node_smtp
node_spa -.->|"shares Trip Book"| node_reports
node_spa -.->|"searches cover photos"| node_pexels

click node_spa "https://github.com/atcasanova/trips/blob/main/client/src/pages/TripDetailPage.tsx"
click node_dashboard "https://github.com/atcasanova/trips/blob/main/client/src/pages/DashboardPage.tsx"
click node_clientapi "https://github.com/atcasanova/trips/blob/main/client/src/api/client.ts"
click node_auth "https://github.com/atcasanova/trips/blob/main/server/src/controllers/authController.ts"
click node_routes "https://github.com/atcasanova/trips/blob/main/server/src/routes/index.ts"
click node_middleware "https://github.com/atcasanova/trips/blob/main/server/src/middleware/auth.ts"
click node_trip "https://github.com/atcasanova/trips/blob/main/server/src/controllers/tripController.ts"
click node_itinerary "https://github.com/atcasanova/trips/blob/main/server/src/controllers/itineraryController.ts"
click node_location "https://github.com/atcasanova/trips/blob/main/server/src/services/itineraryLocationService.ts"
click node_reservations "https://github.com/atcasanova/trips/blob/main/server/src/controllers/reservationController.ts"
click node_expenses "https://github.com/atcasanova/trips/blob/main/server/src/controllers/expenseController.ts"
click node_documents "https://github.com/atcasanova/trips/blob/main/server/src/controllers/documentController.ts"
click node_confirmation "https://github.com/atcasanova/trips/blob/main/server/src/services/documentConfirmationService.ts"
click node_ai "https://github.com/atcasanova/trips/blob/main/server/src/services/openaiService.ts"
click node_emailintake "https://github.com/atcasanova/trips/blob/main/server/src/services/inboundEmailService.ts"
click node_reports "https://github.com/atcasanova/trips/blob/main/server/src/services/reportService.ts"
click node_pdf "https://github.com/atcasanova/trips/blob/main/server/src/services/tripBookPdfService.ts"
click node_admin "https://github.com/atcasanova/trips/blob/main/server/src/controllers/adminController.ts"
click node_db "https://github.com/atcasanova/trips/blob/main/server/src/db/pool.ts"
click node_pdfservice "https://github.com/atcasanova/trips/blob/main/server/src/services/pdfService.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_spa,node_dashboard,node_clientapi toneBlue
class node_auth,node_routes,node_middleware,node_admin toneAmber
class node_trip,node_itinerary,node_location,node_reservations,node_expenses toneMint
class node_documents,node_confirmation,node_ai,node_emailintake,node_reports,node_pdf toneRose
class node_db,node_openai,node_smtp,node_pexels,node_pdfservice,node_traveler toneIndigo
```

## Components

### Web client

- [Trip workspace](https://github.com/atcasanova/trips/blob/main/client/src/pages/TripDetailPage.tsx): `client/src/pages/TripDetailPage.tsx`
- [Trip dashboard](https://github.com/atcasanova/trips/blob/main/client/src/pages/DashboardPage.tsx): `client/src/pages/DashboardPage.tsx`
- [API client](https://github.com/atcasanova/trips/blob/main/client/src/api/client.ts): `client/src/api/client.ts`

### API and access

- [Authentication](https://github.com/atcasanova/trips/blob/main/server/src/controllers/authController.ts): `server/src/controllers/authController.ts`
- [REST routing](https://github.com/atcasanova/trips/blob/main/server/src/routes/index.ts): `server/src/routes/index.ts`
- [Session access](https://github.com/atcasanova/trips/blob/main/server/src/middleware/auth.ts): `server/src/middleware/auth.ts`
- [Administration](https://github.com/atcasanova/trips/blob/main/server/src/controllers/adminController.ts): `server/src/controllers/adminController.ts`

### Trip planning

- [Trip and membership](https://github.com/atcasanova/trips/blob/main/server/src/controllers/tripController.ts): `server/src/controllers/tripController.ts`
- [Itinerary](https://github.com/atcasanova/trips/blob/main/server/src/controllers/itineraryController.ts): `server/src/controllers/itineraryController.ts`
- [Location resolution](https://github.com/atcasanova/trips/blob/main/server/src/services/itineraryLocationService.ts): `server/src/services/itineraryLocationService.ts`
- [Reservations](https://github.com/atcasanova/trips/blob/main/server/src/controllers/reservationController.ts): `server/src/controllers/reservationController.ts`
- [Expense splitting](https://github.com/atcasanova/trips/blob/main/server/src/controllers/expenseController.ts): `server/src/controllers/expenseController.ts`

### Documents and publishing

- [Document management](https://github.com/atcasanova/trips/blob/main/server/src/controllers/documentController.ts): `server/src/controllers/documentController.ts`
- [Document confirmation](https://github.com/atcasanova/trips/blob/main/server/src/services/documentConfirmationService.ts): `server/src/services/documentConfirmationService.ts`
- [AI extraction](https://github.com/atcasanova/trips/blob/main/server/src/services/openaiService.ts): `server/src/services/openaiService.ts`
- [Inbound email](https://github.com/atcasanova/trips/blob/main/server/src/services/inboundEmailService.ts): `server/src/services/inboundEmailService.ts`
- [Trip Book content](https://github.com/atcasanova/trips/blob/main/server/src/services/reportService.ts): `server/src/services/reportService.ts`
- [PDF rendering](https://github.com/atcasanova/trips/blob/main/server/src/services/tripBookPdfService.ts): `server/src/services/tripBookPdfService.ts`

### Persistence and integrations

- [PostgreSQL](https://github.com/atcasanova/trips/blob/main/server/src/db/pool.ts): `server/src/db/pool.ts`
- **OpenAI**
- **SMTP mail**
- **Pexels photos**
- [PDF service](https://github.com/atcasanova/trips/blob/main/server/src/services/pdfService.ts): `server/src/services/pdfService.ts`

### Other components

- **Traveler**

## Connections

- Traveler → Trip dashboard: plans trips
- Trip dashboard → API client: requests data
- Trip workspace → API client: requests trip data
- API client → REST routing: calls REST API
- REST routing → Authentication: routes authentication (evidence: `server/src/routes/index.ts`)
- REST routing → Trip and membership: routes trip requests (evidence: `server/src/routes/index.ts`)
- REST routing → Itinerary: routes itinerary requests (evidence: `server/src/routes/index.ts`)
- REST routing → Reservations: routes reservations (evidence: `server/src/routes/index.ts`)
- REST routing → Expense splitting: routes expenses (evidence: `server/src/routes/index.ts`)
- REST routing → Document management: routes documents (evidence: `server/src/routes/index.ts`)
- REST routing → Administration: routes admin requests (evidence: `server/src/routes/index.ts`)
- Session access → PostgreSQL: checks sessions (evidence: `server/src/middleware/auth.ts`)
- Trip and membership → PostgreSQL: reads and writes (evidence: `server/src/controllers/tripController.ts`)
- Trip and membership → Location resolution: resolves locations (evidence: `server/src/controllers/tripController.ts`)
- Itinerary → PostgreSQL: reads and writes (evidence: `server/src/controllers/itineraryController.ts`)
- Itinerary → Location resolution: refreshes locations (evidence: `server/src/controllers/itineraryController.ts`)
- Itinerary → PDF rendering: requests regeneration (evidence: `server/src/controllers/itineraryController.ts`)
- Location resolution → PostgreSQL: queries trip data (evidence: `server/src/services/itineraryLocationService.ts`)
- Location resolution → OpenAI: resolves places
- Reservations → PostgreSQL: reads and writes (evidence: `server/src/controllers/reservationController.ts`)
- Expense splitting → PostgreSQL: reads and writes (evidence: `server/src/controllers/expenseController.ts`)
- Document management → Document confirmation: confirms extraction
- Document confirmation → AI extraction: extracts document (evidence: `server/src/services/documentConfirmationService.ts`)
- Document confirmation → PostgreSQL: stores confirmations (evidence: `server/src/services/documentConfirmationService.ts`)
- AI extraction → OpenAI: extracts structured data
- AI extraction → PostgreSQL: records AI audit (evidence: `server/src/services/openaiService.ts`)
- Inbound email → AI extraction: analyzes attachments (evidence: `server/src/services/inboundEmailService.ts`)
- Inbound email → Document confirmation: confirms documents (evidence: `server/src/services/inboundEmailService.ts`)
- Inbound email → SMTP mail: sends notifications
- Trip Book content → PostgreSQL: loads trip data (evidence: `server/src/services/reportService.ts`)
- PDF rendering → Trip Book content: builds report HTML (evidence: `server/src/services/tripBookPdfService.ts`)
- PDF rendering → PDF service: renders PDF (evidence: `server/src/services/tripBookPdfService.ts`)
- PDF rendering → PostgreSQL: stores PDF metadata (evidence: `server/src/services/tripBookPdfService.ts`)
- Administration → PostgreSQL: queries metrics (evidence: `server/src/controllers/adminController.ts`)
- Administration → SMTP mail: sends invitations
- Trip and membership → SMTP mail: sends trip invitations (evidence: `server/src/controllers/tripController.ts`)
- Trip workspace → Trip Book content: shares Trip Book
- Trip workspace → Pexels photos: searches cover photos