# frre-ds/2026-13-tpi architecture

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

- Interactive diagram: https://gitdiagram.com/frre-ds/2026-13-tpi
- Repository: https://github.com/frre-ds/2026-13-tpi

## Overview

M5 is a FastAPI service for recording ride requests and managing driver offers through assignment. The principal implemented flow is a client request entering the API, being persisted, then receiving an offer whose response may trigger the transactional assignment service and dispatch history. Reservation-based requests and pre-assignment cancellation are additional API paths. README-listed integrations and candidate search are planned, not shown as live communication; the graph marks those relationships as unverified. The repository also contains a second offer router implementation, but the sampled application entry point registers the other router.

Main entry points: [`app/main.py`](https://github.com/frre-ds/2026-13-tpi/blob/main/app/main.py) (FastAPI entry), [`app/routers/oferta.py`](https://github.com/frre-ds/2026-13-tpi/blob/main/app/routers/oferta.py) (Offer endpoints), [`app/routers/routers_oferta.py`](https://github.com/frre-ds/2026-13-tpi/blob/main/app/routers/routers_oferta.py) (Alternate offer API), [`app/services/asignacion.py`](https://github.com/frre-ds/2026-13-tpi/blob/main/app/services/asignacion.py) (Assignment service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API workflows"]
  node_entry["FastAPI entry<br/>[main.py]"]
  node_request["Request handling<br/>[main.py]"]
end

subgraph group_dispatch["Offers and dispatch"]
  node_offer_api["Offer endpoints<br/>[oferta.py]"]
  node_offer_alt["Alternate offer API<br/>[routers_oferta.py]"]
  node_assignment["Assignment service<br/>[asignacion.py]"]
  node_offer_schema["Offer schemas<br/>[oferta.py]"]
  node_alt_schema["Alternate offer schemas<br/>[schemas_oferta.py]"]
end

subgraph group_persistence["Persistence"]
  node_request_model["Request model<br/>[solicitud.py]"]
  node_offer_model["Offer model<br/>[oferta.py]"]
  node_history_model["Dispatch history model<br/>[despacho.py]"]
  node_database["Database sessions<br/>[database.py]"]
  node_mysql[("MySQL")]
end

subgraph group_integrations["Module integrations"]
  node_m2["M2 clients"]
  node_m3["M3 drivers"]
  node_m4["M4 availability"]
  node_m6["M6 trip lifecycle"]
  node_m9["M9 reservations"]
end

node_client(("Client"))
node_driver(("Driver"))

node_client -->|"submits requests"| node_entry
node_driver -->|"responds to offers"| node_offer_api
node_entry -->|"registers router"| node_offer_api
node_entry -->|"handles requests"| node_request
node_request -->|"opens session"| node_database
node_request -->|"creates and queries"| node_request_model
node_offer_api -->|"opens session"| node_database
node_offer_api -->|"creates and reads"| node_offer_model
node_offer_api -->|"validates payloads"| node_offer_schema
node_offer_api -->|"dispatches response"| node_assignment
node_assignment -->|"checks and updates"| node_offer_model
node_assignment -->|"assigns conductor"| node_request_model
node_assignment -->|"records transition"| node_history_model
node_offer_alt -->|"opens session"| node_database
node_offer_alt -->|"creates and reads"| node_offer_model
node_offer_alt -->|"checks request"| node_request_model
node_offer_alt -->|"records response"| node_history_model
node_offer_alt -->|"validates payloads"| node_alt_schema
node_database -->|"connects to"| node_mysql
node_entry -.->|"planned client checks"| node_m2
node_entry -.->|"planned driver checks"| node_m3
node_entry -.->|"planned availability lookup"| node_m4
node_entry -.->|"planned trip creation"| node_m6
node_entry -.->|"planned reservation activation"| node_m9

click node_entry "https://github.com/frre-ds/2026-13-tpi/blob/main/app/main.py"
click node_request "https://github.com/frre-ds/2026-13-tpi/blob/main/app/main.py"
click node_offer_api "https://github.com/frre-ds/2026-13-tpi/blob/main/app/routers/oferta.py"
click node_offer_alt "https://github.com/frre-ds/2026-13-tpi/blob/main/app/routers/routers_oferta.py"
click node_assignment "https://github.com/frre-ds/2026-13-tpi/blob/main/app/services/asignacion.py"
click node_offer_schema "https://github.com/frre-ds/2026-13-tpi/blob/main/app/schemas/oferta.py"
click node_alt_schema "https://github.com/frre-ds/2026-13-tpi/blob/main/app/schemas/schemas_oferta.py"
click node_request_model "https://github.com/frre-ds/2026-13-tpi/blob/main/app/models/solicitud.py"
click node_offer_model "https://github.com/frre-ds/2026-13-tpi/blob/main/app/models/oferta.py"
click node_history_model "https://github.com/frre-ds/2026-13-tpi/blob/main/app/models/despacho.py"
click node_database "https://github.com/frre-ds/2026-13-tpi/blob/main/app/database.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_entry,node_request,node_client toneBlue
class node_offer_api,node_offer_alt,node_assignment,node_offer_schema,node_alt_schema toneAmber
class node_request_model,node_offer_model,node_history_model,node_database,node_mysql toneMint
class node_m2,node_m3,node_m4,node_m6,node_m9 toneRose
class node_driver toneIndigo
```

## Components

### API workflows

- [FastAPI entry](https://github.com/frre-ds/2026-13-tpi/blob/main/app/main.py): `app/main.py`
- [Request handling](https://github.com/frre-ds/2026-13-tpi/blob/main/app/main.py): `app/main.py`

### Offers and dispatch

- [Offer endpoints](https://github.com/frre-ds/2026-13-tpi/blob/main/app/routers/oferta.py): `app/routers/oferta.py`
- [Alternate offer API](https://github.com/frre-ds/2026-13-tpi/blob/main/app/routers/routers_oferta.py): `app/routers/routers_oferta.py`
- [Assignment service](https://github.com/frre-ds/2026-13-tpi/blob/main/app/services/asignacion.py): `app/services/asignacion.py`
- [Offer schemas](https://github.com/frre-ds/2026-13-tpi/blob/main/app/schemas/oferta.py): `app/schemas/oferta.py`
- [Alternate offer schemas](https://github.com/frre-ds/2026-13-tpi/blob/main/app/schemas/schemas_oferta.py): `app/schemas/schemas_oferta.py`

### Persistence

- [Request model](https://github.com/frre-ds/2026-13-tpi/blob/main/app/models/solicitud.py): `app/models/solicitud.py`
- [Offer model](https://github.com/frre-ds/2026-13-tpi/blob/main/app/models/oferta.py): `app/models/oferta.py`
- [Dispatch history model](https://github.com/frre-ds/2026-13-tpi/blob/main/app/models/despacho.py): `app/models/despacho.py`
- [Database sessions](https://github.com/frre-ds/2026-13-tpi/blob/main/app/database.py): `app/database.py`
- **MySQL**

### Module integrations

- **M2 clients**
- **M3 drivers**
- **M4 availability**
- **M6 trip lifecycle**
- **M9 reservations**

### Other components

- **Client**
- **Driver**

## Connections

- Client → FastAPI entry: submits requests (evidence: `README.md`)
- Driver → Offer endpoints: responds to offers (evidence: `README.md`)
- FastAPI entry → Offer endpoints: registers router (evidence: `app/main.py`)
- FastAPI entry → Request handling: handles requests (evidence: `app/main.py`)
- Request handling → Database sessions: opens session (evidence: `app/main.py`)
- Request handling → Request model: creates and queries (evidence: `app/main.py`)
- Offer endpoints → Database sessions: opens session (evidence: `app/routers/oferta.py`)
- Offer endpoints → Offer model: creates and reads (evidence: `app/routers/oferta.py`)
- Offer endpoints → Offer schemas: validates payloads (evidence: `app/routers/oferta.py`)
- Offer endpoints → Assignment service: dispatches response (evidence: `app/routers/oferta.py`)
- Assignment service → Offer model: checks and updates (evidence: `app/services/asignacion.py`)
- Assignment service → Request model: assigns conductor (evidence: `app/services/asignacion.py`)
- Assignment service → Dispatch history model: records transition (evidence: `app/services/asignacion.py`)
- Alternate offer API → Database sessions: opens session (evidence: `app/routers/routers_oferta.py`)
- Alternate offer API → Offer model: creates and reads (evidence: `app/routers/routers_oferta.py`)
- Alternate offer API → Request model: checks request (evidence: `app/routers/routers_oferta.py`)
- Alternate offer API → Dispatch history model: records response (evidence: `app/routers/routers_oferta.py`)
- Alternate offer API → Alternate offer schemas: validates payloads (evidence: `app/routers/routers_oferta.py`)
- Database sessions → MySQL: connects to (evidence: `app/database.py`)
- FastAPI entry → M2 clients: planned client checks (evidence: `README.md`)
- FastAPI entry → M3 drivers: planned driver checks (evidence: `README.md`)
- FastAPI entry → M4 availability: planned availability lookup (evidence: `README.md`)
- FastAPI entry → M6 trip lifecycle: planned trip creation (evidence: `README.md`)
- FastAPI entry → M9 reservations: planned reservation activation (evidence: `README.md`)
