# yneq/travel-crm-ai architecture

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

- Interactive diagram: https://gitdiagram.com/yneq/travel-crm-ai
- Repository: https://github.com/yneq/travel-crm-ai

## Overview

VoyageOps AI is a staff-facing travel CRM and operations platform. Staff authenticate, manage members and travel requests, build versioned trips and quote snapshots, then progress approved quotes into orders and payment attempts. AI planning and CRM-agent features support that work but keep plans and write proposals under human review. Reminders, communications, audit, and background jobs cover ongoing operations. The map combines sampled calls and imports with explicitly documented capabilities; unsampled subsystems are represented by their existing controller paths, so some links are documented rather than source-verified.

Main entry points: [`app.py`](https://github.com/yneq/travel-crm-ai/blob/main/app.py) (FastAPI application), [`controllers/ai_controller.py`](https://github.com/yneq/travel-crm-ai/blob/main/controllers/ai_controller.py) (AI plan review), [`controllers/reminder_controller.py`](https://github.com/yneq/travel-crm-ai/blob/main/controllers/reminder_controller.py) (Reminders and follow-up), [`services/background_worker.py`](https://github.com/yneq/travel-crm-ai/blob/main/services/background_worker.py) (Background worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_adminui["Operations dashboard<br/>[admin.js]"]
  node_apiapp["FastAPI application<br/>[app.py]"]
  node_identity["Staff identity<br/>[user_controller.py]"]
  node_authdeps["Auth and DB access<br/>[dependencies.py]"]
end

subgraph group_crm["Travel CRM"]
  node_crmctrl["Members and requests<br/>[crm_controller.py]"]
  node_crmrepo[("CRM records and tasks<br/>[crm_repository.py]")]
  node_tripctrl["Trips and quotes<br/>[trip_controller.py]"]
  node_triprepo[("Trip and quote storage<br/>[trip_repository.py]")]
  node_quote["Quote PDF<br/>[quote_pdf.py]"]
  node_payctrl["Orders and payments"]
  node_payrepo[("Payment records")]
end

subgraph group_ai["AI assistance"]
  node_planningctrl["AI plan review<br/>[ai_controller.py]"]
  node_planning["Travel planning provider"]
  node_agentctrl["Agent proposals"]
  node_agentgraph["CRM operations agent"]
  node_agentrepo[("Proposal review state")]
end

subgraph group_ops["Operations governance"]
  node_reminders["Reminders and follow-up"]
  node_communications[("Communication drafts")]
  node_audit["Audit log"]
  node_remrepo[("Reminder records")]
end

subgraph group_runtime["Runtime services"]
  node_worker["Background worker"]
  node_jobs["Job queue<br/>[job_queue.py]"]
  node_jobrepo[("Job records<br/>[job_repository.py]")]
end

node_staff(("Staff user"))
node_mysql[("MySQL")]
node_redis["Redis"]
node_traveler(("Traveler"))

node_staff -->|"uses"| node_adminui
node_adminui -.->|"calls API"| node_apiapp
node_staff -->|"submits requests"| node_apiapp
node_apiapp -->|"routes to"| node_identity
node_apiapp -->|"routes to"| node_crmctrl
node_apiapp -->|"routes to"| node_tripctrl
node_apiapp -->|"routes to"| node_payctrl
node_apiapp -->|"routes to"| node_planningctrl
node_apiapp -->|"routes to"| node_reminders
node_identity -->|"uses auth"| node_authdeps
node_identity -->|"reads and writes"| node_mysql
node_crmctrl -->|"reads and writes"| node_crmrepo
node_crmctrl -->|"checks access"| node_authdeps
node_crmrepo -.->|"persists records"| node_mysql
node_tripctrl -->|"reads and writes"| node_triprepo
node_tripctrl -->|"generates PDF"| node_quote
node_triprepo -.->|"persists trips"| node_mysql
node_payctrl -->|"handles orders"| node_payrepo
node_payrepo -.->|"persists payments"| node_mysql
node_planningctrl -->|"generates drafts"| node_planning
node_planningctrl -.->|"loads CRM context"| node_crmrepo
node_planningctrl -.->|"reviewed plan to itinerary"| node_triprepo
node_agentctrl -->|"runs agent"| node_agentgraph
node_agentctrl -->|"reviews proposals"| node_agentrepo
node_agentgraph -->|"uses tools"| node_agentrepo
node_agentrepo -.->|"stores proposals"| node_mysql
node_reminders -->|"scans and updates"| node_remrepo
node_reminders -->|"drafts follow-up"| node_planning
node_reminders -.->|"manages drafts"| node_communications
node_traveler -.->|"receives approved message"| node_communications
node_communications -.->|"stores drafts"| node_mysql
node_apiapp -->|"routes to"| node_audit
node_worker -->|"recovers and updates"| node_jobrepo
node_worker -->|"scans reminders"| node_remrepo
node_worker -.->|"schedules jobs"| node_jobs
node_jobs -.->|"queues scheduled jobs"| node_redis
node_jobrepo -.->|"stores job state"| node_mysql

click node_adminui "https://github.com/yneq/travel-crm-ai/blob/main/admin/admin.js"
click node_apiapp "https://github.com/yneq/travel-crm-ai/blob/main/app.py"
click node_identity "https://github.com/yneq/travel-crm-ai/blob/main/controllers/user_controller.py"
click node_authdeps "https://github.com/yneq/travel-crm-ai/blob/main/dependencies.py"
click node_crmctrl "https://github.com/yneq/travel-crm-ai/blob/main/controllers/crm_controller.py"
click node_crmrepo "https://github.com/yneq/travel-crm-ai/blob/main/repositories/crm_repository.py"
click node_tripctrl "https://github.com/yneq/travel-crm-ai/blob/main/controllers/trip_controller.py"
click node_triprepo "https://github.com/yneq/travel-crm-ai/blob/main/repositories/trip_repository.py"
click node_quote "https://github.com/yneq/travel-crm-ai/blob/main/services/quote_pdf.py"
click node_payctrl "https://github.com/yneq/travel-crm-ai/blob/main/controllers/payment_controller.py"
click node_payrepo "https://github.com/yneq/travel-crm-ai/blob/main/repositories/payment_repository.py"
click node_planningctrl "https://github.com/yneq/travel-crm-ai/blob/main/controllers/ai_controller.py"
click node_planning "https://github.com/yneq/travel-crm-ai/blob/main/services/planning_provider.py"
click node_agentctrl "https://github.com/yneq/travel-crm-ai/blob/main/controllers/operations_agent_controller.py"
click node_agentgraph "https://github.com/yneq/travel-crm-ai/blob/main/services/operations_agent_graph.py"
click node_agentrepo "https://github.com/yneq/travel-crm-ai/blob/main/repositories/operations_agent_repository.py"
click node_reminders "https://github.com/yneq/travel-crm-ai/blob/main/controllers/reminder_controller.py"
click node_communications "https://github.com/yneq/travel-crm-ai/blob/main/repositories/communication_repository.py"
click node_audit "https://github.com/yneq/travel-crm-ai/blob/main/controllers/audit_controller.py"
click node_worker "https://github.com/yneq/travel-crm-ai/blob/main/services/background_worker.py"
click node_jobs "https://github.com/yneq/travel-crm-ai/blob/main/services/job_queue.py"
click node_jobrepo "https://github.com/yneq/travel-crm-ai/blob/main/repositories/job_repository.py"
click node_remrepo "https://github.com/yneq/travel-crm-ai/blob/main/repositories/reminder_repository.py"

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_adminui,node_apiapp,node_identity,node_authdeps,node_staff toneBlue
class node_crmctrl,node_crmrepo,node_tripctrl,node_triprepo,node_quote,node_payctrl,node_payrepo,node_mysql,node_redis toneAmber
class node_planningctrl,node_planning,node_agentctrl,node_agentgraph,node_agentrepo toneMint
class node_reminders,node_communications,node_audit,node_remrepo toneRose
class node_worker,node_jobs,node_jobrepo,node_traveler toneIndigo
```

## Components

### API and identity

- [Operations dashboard](https://github.com/yneq/travel-crm-ai/blob/main/admin/admin.js): `admin/admin.js`
- [FastAPI application](https://github.com/yneq/travel-crm-ai/blob/main/app.py): `app.py`
- [Staff identity](https://github.com/yneq/travel-crm-ai/blob/main/controllers/user_controller.py): `controllers/user_controller.py`
- [Auth and DB access](https://github.com/yneq/travel-crm-ai/blob/main/dependencies.py): `dependencies.py`

### Travel CRM

- [Members and requests](https://github.com/yneq/travel-crm-ai/blob/main/controllers/crm_controller.py): `controllers/crm_controller.py`
- [CRM records and tasks](https://github.com/yneq/travel-crm-ai/blob/main/repositories/crm_repository.py): `repositories/crm_repository.py`
- [Trips and quotes](https://github.com/yneq/travel-crm-ai/blob/main/controllers/trip_controller.py): `controllers/trip_controller.py`
- [Trip and quote storage](https://github.com/yneq/travel-crm-ai/blob/main/repositories/trip_repository.py): `repositories/trip_repository.py`
- [Quote PDF](https://github.com/yneq/travel-crm-ai/blob/main/services/quote_pdf.py): `services/quote_pdf.py`
- [Orders and payments](https://github.com/yneq/travel-crm-ai/blob/main/controllers/payment_controller.py): `controllers/payment_controller.py`
- [Payment records](https://github.com/yneq/travel-crm-ai/blob/main/repositories/payment_repository.py): `repositories/payment_repository.py`

### AI assistance

- [AI plan review](https://github.com/yneq/travel-crm-ai/blob/main/controllers/ai_controller.py): `controllers/ai_controller.py`
- [Travel planning provider](https://github.com/yneq/travel-crm-ai/blob/main/services/planning_provider.py): `services/planning_provider.py`
- [Agent proposals](https://github.com/yneq/travel-crm-ai/blob/main/controllers/operations_agent_controller.py): `controllers/operations_agent_controller.py`
- [CRM operations agent](https://github.com/yneq/travel-crm-ai/blob/main/services/operations_agent_graph.py): `services/operations_agent_graph.py`
- [Proposal review state](https://github.com/yneq/travel-crm-ai/blob/main/repositories/operations_agent_repository.py): `repositories/operations_agent_repository.py`

### Operations governance

- [Reminders and follow-up](https://github.com/yneq/travel-crm-ai/blob/main/controllers/reminder_controller.py): `controllers/reminder_controller.py`
- [Communication drafts](https://github.com/yneq/travel-crm-ai/blob/main/repositories/communication_repository.py): `repositories/communication_repository.py`
- [Audit log](https://github.com/yneq/travel-crm-ai/blob/main/controllers/audit_controller.py): `controllers/audit_controller.py`
- [Reminder records](https://github.com/yneq/travel-crm-ai/blob/main/repositories/reminder_repository.py): `repositories/reminder_repository.py`

### Runtime services

- [Background worker](https://github.com/yneq/travel-crm-ai/blob/main/services/background_worker.py): `services/background_worker.py`
- [Job queue](https://github.com/yneq/travel-crm-ai/blob/main/services/job_queue.py): `services/job_queue.py`
- [Job records](https://github.com/yneq/travel-crm-ai/blob/main/repositories/job_repository.py): `repositories/job_repository.py`

### Other components

- **Staff user**
- **MySQL**
- **Redis**
- **Traveler**

## Connections

- Staff user → Operations dashboard: uses (evidence: `README.md`)
- Operations dashboard → FastAPI application: calls API (evidence: `README.md`)
- Staff user → FastAPI application: submits requests (evidence: `README.md`)
- FastAPI application → Staff identity: routes to (evidence: `app.py`)
- FastAPI application → Members and requests: routes to (evidence: `app.py`)
- FastAPI application → Trips and quotes: routes to (evidence: `app.py`)
- FastAPI application → Orders and payments: routes to (evidence: `app.py`)
- FastAPI application → AI plan review: routes to (evidence: `app.py`)
- FastAPI application → Reminders and follow-up: routes to (evidence: `app.py`)
- Staff identity → Auth and DB access: uses auth (evidence: `controllers/user_controller.py`)
- Staff identity → MySQL: reads and writes (evidence: `controllers/user_controller.py`)
- Members and requests → CRM records and tasks: reads and writes (evidence: `controllers/crm_controller.py`)
- Members and requests → Auth and DB access: checks access (evidence: `controllers/crm_controller.py`)
- CRM records and tasks → MySQL: persists records (evidence: `README.md`)
- Trips and quotes → Trip and quote storage: reads and writes (evidence: `controllers/trip_controller.py`)
- Trips and quotes → Quote PDF: generates PDF (evidence: `controllers/trip_controller.py`)
- Trip and quote storage → MySQL: persists trips (evidence: `README.md`)
- Orders and payments → Payment records: handles orders (evidence: `controllers/payment_controller.py`)
- Payment records → MySQL: persists payments (evidence: `README.md`)
- AI plan review → Travel planning provider: generates drafts (evidence: `controllers/ai_controller.py`)
- AI plan review → CRM records and tasks: loads CRM context (evidence: `README.md`)
- AI plan review → Trip and quote storage: reviewed plan to itinerary (evidence: `README.md`)
- Agent proposals → CRM operations agent: runs agent (evidence: `controllers/operations_agent_controller.py`)
- Agent proposals → Proposal review state: reviews proposals (evidence: `controllers/operations_agent_controller.py`)
- CRM operations agent → Proposal review state: uses tools (evidence: `services/operations_agent_graph.py`)
- Proposal review state → MySQL: stores proposals (evidence: `README.md`)
- Reminders and follow-up → Reminder records: scans and updates (evidence: `controllers/reminder_controller.py`)
- Reminders and follow-up → Travel planning provider: drafts follow-up (evidence: `controllers/reminder_controller.py`)
- Reminders and follow-up → Communication drafts: manages drafts (evidence: `README.md`)
- Traveler → Communication drafts: receives approved message (evidence: `README.md`)
- Communication drafts → MySQL: stores drafts (evidence: `README.md`)
- FastAPI application → Audit log: routes to (evidence: `app.py`)
- Background worker → Job records: recovers and updates (evidence: `services/background_worker.py`)
- Background worker → Reminder records: scans reminders (evidence: `services/background_worker.py`)
- Background worker → Job queue: schedules jobs (evidence: `README.md`)
- Job queue → Redis: queues scheduled jobs (evidence: `README.md`)
- Job records → MySQL: stores job state (evidence: `README.md`)
