# cfi21/m3-nvocc-erp architecture

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

- Interactive diagram: https://gitdiagram.com/cfi21/m3-nvocc-erp
- Repository: https://github.com/cfi21/m3-nvocc-erp
- Video tour (about a minute): https://gitdiagram.com/cfi21/m3-nvocc-erp/video

## Overview

M3 NVOCC ERP is a FastAPI application for freight-forwarding operations, finance, equipment/container management, and administration. The principal workflow is an authenticated user submitting work through the API, where domain modules manage operational and financial records in the database; screen and reporting endpoints expose that work. The README describes PostgreSQL/Supabase as the database target and states that production traffic, live providers, and real-money movement are off. Connections among unsampled modules are omitted unless the source index or excerpts establish them.

Main entry points: [`app/main.py`](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/main.py) (FastAPI runtime), [`app/db.py`](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/db.py) (Database adapter), [`app/screen_integration.py`](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/screen_integration.py) (Screen integration), [`app/bulk.py`](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/bulk.py) (Bulk processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_api["FastAPI runtime<br/>[main.py]"]
  node_admin["Identity and admin<br/>[admin.py]"]
  node_screens["Screen integration"]
  node_catalog["Screen catalog<br/>[screen_catalog.py]"]
end

subgraph group_operations["Freight operations"]
  node_operations["Operational workflows"]
  node_businessday["Business-day simulation<br/>[business_day.py]"]
  node_integration["External integrations<br/>[integration.py]"]
  node_bulk["Bulk processing<br/>[bulk.py]"]
end

subgraph group_finance["Finance and treasury"]
  node_financecontrols["Finance controls"]
  node_gl["General ledger<br/>[gl.py]"]
  node_treasury["Treasury<br/>[treasury.py]"]
  node_reports["GL reporting"]
end

subgraph group_equipment["Equipment control"]
  node_equipmaster["Container master control"]
  node_journey["Container journey"]
  node_network["Equipment network"]
end

subgraph group_governance["Data and readiness"]
  node_masterdata["Master data governance<br/>[masterdata.py]"]
  node_readiness["Preproduction checks<br/>[preprod.py]"]
  node_providers["Provider runtime"]
  node_db["Database adapter<br/>[db.py]"]
end

node_user(("ERP user"))
node_postgres[("PostgreSQL")]

node_user -->|"submits work"| node_api
node_api -->|"registers routes"| node_admin
node_api -->|"registers routes"| node_screens
node_api -->|"registers routes"| node_businessday
node_api -->|"imports"| node_operations
node_api -->|"imports"| node_integration
node_api -->|"imports"| node_bulk
node_api -->|"imports"| node_gl
node_api -->|"imports"| node_treasury
node_api -->|"imports"| node_masterdata
node_api -->|"imports"| node_readiness
node_api -->|"imports"| node_providers
node_screens -->|"builds catalog"| node_catalog
node_screens -->|"uses report rows"| node_reports
node_businessday -->|"connects to"| node_db
node_equipmaster -->|"connects to"| node_db
node_journey -->|"connects to"| node_db
node_journey -->|"resolves containers"| node_equipmaster
node_network -->|"uses container control"| node_equipmaster
node_network -->|"uses journey data"| node_journey
node_financecontrols -->|"reads and writes"| node_db
node_gl -->|"connects to"| node_db
node_treasury -->|"uses ledger"| node_gl
node_treasury -->|"uses approval fast-track"| node_financecontrols
node_masterdata -->|"connects to"| node_db
node_readiness -->|"ensures default run"| node_businessday
node_readiness -->|"checks database"| node_db
node_providers -->|"connects to"| node_db
node_admin -->|"reads and writes"| node_db
node_bulk -->|"reads and writes"| node_db
node_bulk -->|"recovers JSON arrays"| node_api
node_db -->|"connects when configured"| node_postgres

click node_api "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/main.py"
click node_admin "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/admin.py"
click node_screens "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/screen_integration.py"
click node_catalog "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/screen_catalog.py"
click node_operations "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/operations_workbench.py"
click node_businessday "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/business_day.py"
click node_integration "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/integration.py"
click node_bulk "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/bulk.py"
click node_equipmaster "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/clx070_container_master_control.py"
click node_journey "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/clx071_container_journey.py"
click node_network "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/clx072_equipment_network.py"
click node_financecontrols "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/clx032_finance_controls.py"
click node_gl "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/gl.py"
click node_treasury "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/treasury.py"
click node_reports "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/clx045_gl_reporting.py"
click node_masterdata "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/masterdata.py"
click node_readiness "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/preprod.py"
click node_providers "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/live_provider_runtime.py"
click node_db "https://github.com/cfi21/m3-nvocc-erp/blob/main/app/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_api,node_admin,node_screens,node_catalog,node_user toneBlue
class node_operations,node_businessday,node_integration,node_bulk,node_postgres toneAmber
class node_financecontrols,node_gl,node_treasury,node_reports toneMint
class node_equipmaster,node_journey,node_network toneRose
class node_masterdata,node_readiness,node_providers,node_db toneIndigo
```

## Components

### API and access

- [FastAPI runtime](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/main.py): `app/main.py`
- [Identity and admin](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/admin.py): `app/admin.py`
- [Screen integration](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/screen_integration.py): `app/screen_integration.py`
- [Screen catalog](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/screen_catalog.py): `app/screen_catalog.py`

### Freight operations

- [Operational workflows](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/operations_workbench.py): `app/operations_workbench.py`
- [Business-day simulation](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/business_day.py): `app/business_day.py`
- [External integrations](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/integration.py): `app/integration.py`
- [Bulk processing](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/bulk.py): `app/bulk.py`

### Finance and treasury

- [Finance controls](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/clx032_finance_controls.py): `app/clx032_finance_controls.py`
- [General ledger](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/gl.py): `app/gl.py`
- [Treasury](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/treasury.py): `app/treasury.py`
- [GL reporting](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/clx045_gl_reporting.py): `app/clx045_gl_reporting.py`

### Equipment control

- [Container master control](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/clx070_container_master_control.py): `app/clx070_container_master_control.py`
- [Container journey](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/clx071_container_journey.py): `app/clx071_container_journey.py`
- [Equipment network](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/clx072_equipment_network.py): `app/clx072_equipment_network.py`

### Data and readiness

- [Master data governance](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/masterdata.py): `app/masterdata.py`
- [Preproduction checks](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/preprod.py): `app/preprod.py`
- [Provider runtime](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/live_provider_runtime.py): `app/live_provider_runtime.py`
- [Database adapter](https://github.com/cfi21/m3-nvocc-erp/blob/main/app/db.py): `app/db.py`

### Other components

- **ERP user**
- **PostgreSQL**

## Connections

- ERP user → FastAPI runtime: submits work (evidence: `app/main.py`)
- FastAPI runtime → Identity and admin: registers routes (evidence: `app/main.py`)
- FastAPI runtime → Screen integration: registers routes (evidence: `app/main.py`)
- FastAPI runtime → Business-day simulation: registers routes (evidence: `app/main.py`)
- FastAPI runtime → Operational workflows: imports (evidence: `app/main.py`)
- FastAPI runtime → External integrations: imports (evidence: `app/main.py`)
- FastAPI runtime → Bulk processing: imports (evidence: `app/main.py`)
- FastAPI runtime → General ledger: imports (evidence: `app/main.py`)
- FastAPI runtime → Treasury: imports (evidence: `app/main.py`)
- FastAPI runtime → Master data governance: imports (evidence: `app/main.py`)
- FastAPI runtime → Preproduction checks: imports (evidence: `app/main.py`)
- FastAPI runtime → Provider runtime: imports (evidence: `app/main.py`)
- Screen integration → Screen catalog: builds catalog (evidence: `app/screen_integration.py`)
- Screen integration → GL reporting: uses report rows (evidence: `app/screen_integration.py`)
- Business-day simulation → Database adapter: connects to (evidence: `app/business_day.py`)
- Container master control → Database adapter: connects to (evidence: `app/clx070_container_master_control.py`)
- Container journey → Database adapter: connects to (evidence: `app/clx071_container_journey.py`)
- Container journey → Container master control: resolves containers (evidence: `app/clx071_container_journey.py`)
- Equipment network → Container master control: uses container control (evidence: `app/clx072_equipment_network.py`)
- Equipment network → Container journey: uses journey data (evidence: `app/clx072_equipment_network.py`)
- Finance controls → Database adapter: reads and writes (evidence: `app/clx032_finance_controls.py`)
- General ledger → Database adapter: connects to (evidence: `app/gl.py`)
- Treasury → General ledger: uses ledger (evidence: `app/treasury.py`)
- Treasury → Finance controls: uses approval fast-track (evidence: `app/treasury.py`)
- Master data governance → Database adapter: connects to (evidence: `app/masterdata.py`)
- Preproduction checks → Business-day simulation: ensures default run (evidence: `app/preprod.py`)
- Preproduction checks → Database adapter: checks database (evidence: `app/preprod.py`)
- Provider runtime → Database adapter: connects to (evidence: `app/live_provider_runtime.py`)
- Identity and admin → Database adapter: reads and writes (evidence: `app/admin.py`)
- Bulk processing → Database adapter: reads and writes (evidence: `app/bulk.py`)
- Bulk processing → FastAPI runtime: recovers JSON arrays (evidence: `app/bulk.py`)
- Database adapter → PostgreSQL: connects when configured