# protogulix/tunnel-backend architecture

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

- Interactive diagram: https://gitdiagram.com/protogulix/tunnel-backend
- Repository: https://github.com/protogulix/tunnel-backend

## Overview

Tunnel GMAO is a maintenance-management backend API for industrial teams. Users and integrations call the FastAPI application to manage equipment and intervention requests; accepted requests can lead to interventions, whose tasks and actions record execution, time, complexity, and parts. Preventive maintenance, stock and purchasing, reporting, and exports support the wider maintenance workflow. Repository routes delegate many operations to domain repositories and database access. Some capabilities are documented in the README and tree but their implementation was not sampled, so their internal wiring is shown only where supported.

Main entry points: [`api/app.py`](https://github.com/protogulix/tunnel-backend/blob/main/api/app.py) (API application), [`api/interventions/routes.py`](https://github.com/protogulix/tunnel-backend/blob/main/api/interventions/routes.py) (Interventions), [`api/db.py`](https://github.com/protogulix/tunnel-backend/blob/main/api/db.py) (Database access), [`api/intervention_requests/routes.py`](https://github.com/protogulix/tunnel-backend/blob/main/api/intervention_requests/routes.py) (Intervention requests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and identity"]
  node_app["API application<br/>[app.py]"]
  node_auth["Authentication<br/>[routes.py]"]
  node_keys["API keys<br/>[routes.py]"]
end

subgraph group_maintenance["Maintenance work"]
  node_equipment["Equipment<br/>[routes.py]"]
  node_requests["Intervention requests<br/>[routes.py]"]
  node_interventions["Interventions<br/>[routes.py]"]
  node_tasks["Work tasks<br/>[routes.py]"]
  node_actions["Work actions<br/>[routes.py]"]
  node_preventive["Preventive maintenance"]
  node_occurrences["Plan occurrences"]
end

subgraph group_supply["Stock and purchasing"]
  node_stock["Stock catalogue"]
  node_parts["Parts catalogue<br/>[routes.py]"]
  node_templates["Part templates"]
  node_purchase["Purchase requests<br/>[routes.py]"]
  node_orders["Supplier orders<br/>[routes.py]"]
  node_orderlines["Order lines<br/>[routes.py]"]
end

subgraph group_insight["Reporting and exports"]
  node_dashboard["Dashboard and stats"]
  node_exports["PDF and QR exports<br/>[routes.py]"]
  node_audit["Audit trail"]
end

subgraph group_persistence["Persistence"]
  node_dbaccess["Database access<br/>[db.py]"]
  node_postgres[("PostgreSQL")]
end

node_users(("Users and integrations"))

node_users -->|"sends requests"| node_app
node_app -->|"dispatches"| node_auth
node_app -->|"dispatches"| node_keys
node_app -->|"dispatches"| node_equipment
node_app -->|"dispatches"| node_requests
node_app -->|"dispatches"| node_interventions
node_app -->|"dispatches"| node_tasks
node_app -->|"dispatches"| node_actions
node_app -->|"dispatches"| node_preventive
node_app -->|"dispatches"| node_occurrences
node_app -->|"dispatches"| node_stock
node_app -->|"dispatches"| node_parts
node_app -->|"dispatches"| node_templates
node_app -->|"dispatches"| node_purchase
node_app -->|"dispatches"| node_orders
node_app -->|"dispatches"| node_orderlines
node_app -->|"dispatches"| node_dashboard
node_app -->|"dispatches"| node_exports
node_requests -->|"creates on acceptance"| node_interventions
node_interventions -->|"associates work"| node_equipment
node_interventions -->|"loads actions"| node_actions
node_tasks -->|"requires for completion"| node_actions
node_preventive -->|"manages occurrences"| node_occurrences
node_purchase -->|"dispatches requests"| node_orders
node_orders -->|"manages lines"| node_orderlines
node_interventions -->|"reads and writes"| node_dbaccess
node_requests -->|"reads and writes"| node_dbaccess
node_auth -->|"reads and writes"| node_dbaccess
node_dbaccess -->|"queries"| node_postgres
node_exports -->|"loads intervention data"| node_interventions
node_exports -->|"loads planning data"| node_dbaccess

click node_app "https://github.com/protogulix/tunnel-backend/blob/main/api/app.py"
click node_auth "https://github.com/protogulix/tunnel-backend/blob/main/api/auth/routes.py"
click node_keys "https://github.com/protogulix/tunnel-backend/blob/main/api/api_keys/routes.py"
click node_equipment "https://github.com/protogulix/tunnel-backend/blob/main/api/equipements/routes.py"
click node_requests "https://github.com/protogulix/tunnel-backend/blob/main/api/intervention_requests/routes.py"
click node_interventions "https://github.com/protogulix/tunnel-backend/blob/main/api/interventions/routes.py"
click node_tasks "https://github.com/protogulix/tunnel-backend/blob/main/api/intervention_tasks/routes.py"
click node_actions "https://github.com/protogulix/tunnel-backend/blob/main/api/intervention_actions/routes.py"
click node_preventive "https://github.com/protogulix/tunnel-backend/tree/main/api/preventive_plans"
click node_occurrences "https://github.com/protogulix/tunnel-backend/tree/main/api/preventive_occurrences"
click node_stock "https://github.com/protogulix/tunnel-backend/tree/main/api/stock_items"
click node_parts "https://github.com/protogulix/tunnel-backend/blob/main/api/parts/routes.py"
click node_templates "https://github.com/protogulix/tunnel-backend/tree/main/api/part_templates"
click node_purchase "https://github.com/protogulix/tunnel-backend/blob/main/api/purchase_requests/routes.py"
click node_orders "https://github.com/protogulix/tunnel-backend/blob/main/api/supplier_orders/routes.py"
click node_orderlines "https://github.com/protogulix/tunnel-backend/blob/main/api/supplier_order_lines/routes.py"
click node_dashboard "https://github.com/protogulix/tunnel-backend/tree/main/api/dashboard"
click node_exports "https://github.com/protogulix/tunnel-backend/blob/main/api/exports/routes.py"
click node_audit "https://github.com/protogulix/tunnel-backend/tree/main/api/audits"
click node_dbaccess "https://github.com/protogulix/tunnel-backend/blob/main/api/db.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_app,node_auth,node_keys,node_users toneBlue
class node_equipment,node_requests,node_interventions,node_tasks,node_actions,node_preventive,node_occurrences toneAmber
class node_stock,node_parts,node_templates,node_purchase,node_orders,node_orderlines toneMint
class node_dashboard,node_exports,node_audit toneRose
class node_dbaccess,node_postgres toneIndigo
```

## Components

### API and identity

- [API application](https://github.com/protogulix/tunnel-backend/blob/main/api/app.py): `api/app.py`
- [Authentication](https://github.com/protogulix/tunnel-backend/blob/main/api/auth/routes.py): `api/auth/routes.py`
- [API keys](https://github.com/protogulix/tunnel-backend/blob/main/api/api_keys/routes.py): `api/api_keys/routes.py`

### Maintenance work

- [Equipment](https://github.com/protogulix/tunnel-backend/blob/main/api/equipements/routes.py): `api/equipements/routes.py`
- [Intervention requests](https://github.com/protogulix/tunnel-backend/blob/main/api/intervention_requests/routes.py): `api/intervention_requests/routes.py`
- [Interventions](https://github.com/protogulix/tunnel-backend/blob/main/api/interventions/routes.py): `api/interventions/routes.py`
- [Work tasks](https://github.com/protogulix/tunnel-backend/blob/main/api/intervention_tasks/routes.py): `api/intervention_tasks/routes.py`
- [Work actions](https://github.com/protogulix/tunnel-backend/blob/main/api/intervention_actions/routes.py): `api/intervention_actions/routes.py`
- [Preventive maintenance](https://github.com/protogulix/tunnel-backend/tree/main/api/preventive_plans): `api/preventive_plans`
- [Plan occurrences](https://github.com/protogulix/tunnel-backend/tree/main/api/preventive_occurrences): `api/preventive_occurrences`

### Stock and purchasing

- [Stock catalogue](https://github.com/protogulix/tunnel-backend/tree/main/api/stock_items): `api/stock_items`
- [Parts catalogue](https://github.com/protogulix/tunnel-backend/blob/main/api/parts/routes.py): `api/parts/routes.py`
- [Part templates](https://github.com/protogulix/tunnel-backend/tree/main/api/part_templates): `api/part_templates`
- [Purchase requests](https://github.com/protogulix/tunnel-backend/blob/main/api/purchase_requests/routes.py): `api/purchase_requests/routes.py`
- [Supplier orders](https://github.com/protogulix/tunnel-backend/blob/main/api/supplier_orders/routes.py): `api/supplier_orders/routes.py`
- [Order lines](https://github.com/protogulix/tunnel-backend/blob/main/api/supplier_order_lines/routes.py): `api/supplier_order_lines/routes.py`

### Reporting and exports

- [Dashboard and stats](https://github.com/protogulix/tunnel-backend/tree/main/api/dashboard): `api/dashboard`
- [PDF and QR exports](https://github.com/protogulix/tunnel-backend/blob/main/api/exports/routes.py): `api/exports/routes.py`
- [Audit trail](https://github.com/protogulix/tunnel-backend/tree/main/api/audits): `api/audits`

### Persistence

- [Database access](https://github.com/protogulix/tunnel-backend/blob/main/api/db.py): `api/db.py`
- **PostgreSQL**

### Other components

- **Users and integrations**

## Connections

- Users and integrations → API application: sends requests
- API application → Authentication: dispatches
- API application → API keys: dispatches
- API application → Equipment: dispatches
- API application → Intervention requests: dispatches
- API application → Interventions: dispatches
- API application → Work tasks: dispatches
- API application → Work actions: dispatches
- API application → Preventive maintenance: dispatches
- API application → Plan occurrences: dispatches
- API application → Stock catalogue: dispatches
- API application → Parts catalogue: dispatches
- API application → Part templates: dispatches
- API application → Purchase requests: dispatches
- API application → Supplier orders: dispatches
- API application → Order lines: dispatches
- API application → Dashboard and stats: dispatches
- API application → PDF and QR exports: dispatches
- Intervention requests → Interventions: creates on acceptance
- Interventions → Equipment: associates work
- Interventions → Work actions: loads actions
- Work tasks → Work actions: requires for completion
- Preventive maintenance → Plan occurrences: manages occurrences
- Purchase requests → Supplier orders: dispatches requests
- Supplier orders → Order lines: manages lines
- Interventions → Database access: reads and writes
- Intervention requests → Database access: reads and writes
- Authentication → Database access: reads and writes
- Database access → PostgreSQL: queries
- PDF and QR exports → Interventions: loads intervention data
- PDF and QR exports → Database access: loads planning data