# gulmezeren2-byte/erp-report-engine architecture

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

- Interactive diagram: https://gitdiagram.com/gulmezeren2-byte/erp-report-engine
- Repository: https://github.com/gulmezeren2-byte/erp-report-engine

## Overview

erp-report-engine is a read-only ERP analytics product with two principal use cases: scheduled weekly reporting and guarded AI-agent access. The report workflow maps ERP schemas to canonical entities, reads and checks source data, computes operational measures and signals, then renders and optionally delivers results. A Power BI export is another documented output. The graph follows README-described flows and sampled module responsibilities; several internal call details and unsampled subsystem wiring are not established by the excerpts, so uncertain links are omitted.

Main entry points: [`erp_report_engine/runner.py`](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/runner.py) (Run orchestrator), [`erp_report_engine/cli.py`](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/cli.py) (CLI), [`erp_report_engine/extract.py`](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/extract.py) (Canonical extraction), [`erp_report_engine/mcp_server.py`](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/mcp_server.py) (Guarded MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and configuration"]
  node_cli["CLI<br/>[cli.py]"]
  node_runner["Run orchestrator<br/>[runner.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_profiles["ERP profiles"]
end

subgraph group_access["Safe data access"]
  node_connect["Database connection<br/>[connect.py]"]
  node_guard["Read-only guard<br/>[guard.py]"]
  node_extract["Canonical extraction<br/>[extract.py]"]
  node_contracts["Quality and reconciliation<br/>[contracts.py]"]
end

subgraph group_analytics["Report analytics"]
  node_kpi["KPI computation<br/>[kpi.py]"]
  node_spc["Control signals<br/>[spc.py]"]
  node_insights["Findings and drivers<br/>[insights.py]"]
  node_narrate["Report narration<br/>[narrate.py]"]
  node_state[("Run memory<br/>[state.py]")]
end

subgraph group_outputs["Reporting outputs"]
  node_html["HTML reports<br/>[render.py]"]
  node_dashboard["Command Center"]
  node_delivery["Report delivery<br/>[delivery.py]"]
  node_powerbi_export["Power BI export<br/>[export_powerbi.py]"]
  node_powerbi_model["Power BI model"]
end

subgraph group_agent["Agent access"]
  node_mcp["Guarded MCP server<br/>[mcp_server.py]"]
end

node_operator(("Operator"))
node_erp[("ERP SQL database")]
node_agent_actor(("AI agent"))

node_operator -->|"invokes"| node_cli
node_cli -->|"runs report"| node_runner
node_runner -->|"loads settings"| node_config
node_config -->|"selects profile"| node_profiles
node_runner -->|"requests extraction"| node_extract
node_extract -->|"queries through"| node_connect
node_connect -->|"opens read-only session"| node_erp
node_extract -->|"checks SQL"| node_guard
node_extract -->|"reconciles and flags"| node_contracts
node_runner -->|"computes measures"| node_kpi
node_runner -->|"evaluates signals"| node_spc
node_runner -->|"builds findings"| node_insights
node_runner -->|"prepares report text"| node_narrate
node_runner -->|"updates run memory"| node_state
node_runner -->|"renders report"| node_html
node_runner -->|"renders dashboard"| node_dashboard
node_cli -.->|"optionally sends"| node_delivery
node_cli -->|"exports data"| node_powerbi_export
node_powerbi_export -->|"writes model data"| node_powerbi_model
node_agent_actor -->|"requests tools"| node_mcp
node_mcp -->|"guards queries"| node_guard
node_mcp -->|"reads canonical data"| node_erp

click node_cli "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/cli.py"
click node_runner "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/runner.py"
click node_config "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/config.py"
click node_profiles "https://github.com/gulmezeren2-byte/erp-report-engine/tree/main/erp_report_engine/profiles"
click node_connect "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/connect.py"
click node_guard "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/guard.py"
click node_extract "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/extract.py"
click node_contracts "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/contracts.py"
click node_kpi "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/kpi.py"
click node_spc "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/spc.py"
click node_insights "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/insights.py"
click node_narrate "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/narrate.py"
click node_state "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/state.py"
click node_html "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/render.py"
click node_dashboard "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/render_dashboard.py"
click node_delivery "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/delivery.py"
click node_powerbi_export "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/export_powerbi.py"
click node_powerbi_model "https://github.com/gulmezeren2-byte/erp-report-engine/tree/main/powerbi/ERP%20Command%20Center.SemanticModel"
click node_mcp "https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/mcp_server.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_cli,node_runner,node_config,node_profiles toneBlue
class node_connect,node_guard,node_extract,node_contracts,node_erp toneAmber
class node_kpi,node_spc,node_insights,node_narrate,node_state toneMint
class node_html,node_dashboard,node_delivery,node_powerbi_export,node_powerbi_model toneRose
class node_mcp,node_operator,node_agent_actor toneIndigo
```

## Components

### Entry and configuration

- [CLI](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/cli.py): `erp_report_engine/cli.py`
- [Run orchestrator](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/runner.py): `erp_report_engine/runner.py`
- [Configuration](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/config.py): `erp_report_engine/config.py`
- [ERP profiles](https://github.com/gulmezeren2-byte/erp-report-engine/tree/main/erp_report_engine/profiles): `erp_report_engine/profiles`

### Safe data access

- [Database connection](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/connect.py): `erp_report_engine/connect.py`
- [Read-only guard](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/guard.py): `erp_report_engine/guard.py`
- [Canonical extraction](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/extract.py): `erp_report_engine/extract.py`
- [Quality and reconciliation](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/contracts.py): `erp_report_engine/contracts.py`

### Report analytics

- [KPI computation](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/kpi.py): `erp_report_engine/kpi.py`
- [Control signals](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/spc.py): `erp_report_engine/spc.py`
- [Findings and drivers](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/insights.py): `erp_report_engine/insights.py`
- [Report narration](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/narrate.py): `erp_report_engine/narrate.py`
- [Run memory](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/state.py): `erp_report_engine/state.py`

### Reporting outputs

- [HTML reports](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/render.py): `erp_report_engine/render.py`
- [Command Center](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/render_dashboard.py): `erp_report_engine/render_dashboard.py`
- [Report delivery](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/delivery.py): `erp_report_engine/delivery.py`
- [Power BI export](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/export_powerbi.py): `erp_report_engine/export_powerbi.py`
- [Power BI model](https://github.com/gulmezeren2-byte/erp-report-engine/tree/main/powerbi/ERP%20Command%20Center.SemanticModel): `powerbi/ERP Command Center.SemanticModel`

### Agent access

- [Guarded MCP server](https://github.com/gulmezeren2-byte/erp-report-engine/blob/main/erp_report_engine/mcp_server.py): `erp_report_engine/mcp_server.py`

### Other components

- **Operator**
- **ERP SQL database**
- **AI agent**

## Connections

- Operator → CLI: invokes
- CLI → Run orchestrator: runs report
- Run orchestrator → Configuration: loads settings
- Configuration → ERP profiles: selects profile
- Run orchestrator → Canonical extraction: requests extraction
- Canonical extraction → Database connection: queries through
- Database connection → ERP SQL database: opens read-only session
- Canonical extraction → Read-only guard: checks SQL
- Canonical extraction → Quality and reconciliation: reconciles and flags
- Run orchestrator → KPI computation: computes measures
- Run orchestrator → Control signals: evaluates signals
- Run orchestrator → Findings and drivers: builds findings
- Run orchestrator → Report narration: prepares report text
- Run orchestrator → Run memory: updates run memory
- Run orchestrator → HTML reports: renders report
- Run orchestrator → Command Center: renders dashboard
- CLI → Report delivery: optionally sends
- CLI → Power BI export: exports data
- Power BI export → Power BI model: writes model data
- AI agent → Guarded MCP server: requests tools
- Guarded MCP server → Read-only guard: guards queries
- Guarded MCP server → ERP SQL database: reads canonical data