# guyc21/mailtoexcelautomation architecture

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

- Interactive diagram: https://gitdiagram.com/guyc21/mailtoexcelautomation
- Repository: https://github.com/guyc21/mailtoexcelautomation

## Overview

GoldenCare automates Hebrew finance-document intake and provides a backoffice for review, prompt management, sandbox testing, and regression evaluation. Its main workflow accepts email attachments or sandbox uploads, stores and extracts each document, applies deterministic business checks, records an audit trail, and syncs pending results to the Excel workbook. The graph also preserves dashboard, review, prompt, and ground-truth regression capabilities. Some subsystems are represented from README and source-index references; unsampled UI/API wiring is not inferred.

Main entry points: [`frontend/src/App.jsx`](https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/App.jsx) (Backoffice app), [`backend/services/ingestion_pipeline.py`](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/ingestion_pipeline.py) (Ingestion orchestrator), [`backend/api/routes/email.py`](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/api/routes/email.py) (Email endpoints), [`backend/models/ingestion.py`](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/models/ingestion.py) (Ingestion audit records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backoffice["Backoffice UI"]
  node_frontend_app["Backoffice app<br/>[App.jsx]"]
  node_dashboard_ui["Dashboard<br/>[DashboardPage.jsx]"]
  node_prompt_ui["Prompt management<br/>[HomePage.jsx]"]
  node_sandbox_ui["Sandbox<br/>[SandboxPage.jsx]"]
  node_review_ui["Document review<br/>[ReviewPage.jsx]"]
  node_regression_ui["Regression testing<br/>[RegressionPage.jsx]"]
  node_labeling_ui["Ground-truth labeling<br/>[LabelingPage.jsx]"]
  node_prompt_routes["Prompt endpoints<br/>[prompts.py]"]
  node_document_routes["Review endpoints<br/>[documents.py]"]
  node_dashboard_routes["Dashboard endpoints<br/>[dashboard.py]"]
end

subgraph group_intake["Document Intake"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_email_routes["Email endpoints<br/>[email.py]"]
  node_sandbox_route["Sandbox upload<br/>[ingestion.py]"]
  node_email_parser["Email parsing<br/>[email_parser.py]"]
  node_file_storage["File storage<br/>[file_storage.py]"]
  node_ingestion_pipeline["Ingestion orchestrator"]
end

subgraph group_extraction["Extraction and Validation"]
  node_extractor["Document extractor<br/>[extractor.py]"]
  node_envelope["System envelope<br/>[system_envelope.py]"]
  node_providers["Provider adapters"]
  node_business_rules["Business validation<br/>[business_rules.py]"]
end

subgraph group_records["Audit and Excel"]
  node_database[("Operational database<br/>[database.py]")]
  node_ingestion_records["Ingestion audit records<br/>[ingestion.py]"]
  node_excel_sync["Workbook synchronization<br/>[excel_sync.py]"]
  node_excel_repository[("Excel workbook")]
end

subgraph group_regression["Regression Suite"]
  node_regression_routes["Regression endpoints<br/>[regression.py]"]
  node_regression_runner["Regression runner<br/>[runner.py]"]
  node_regression_scorer["Regression scorer<br/>[scorer.py]"]
  node_labeling_service["Labeling service<br/>[labeling.py]"]
end

node_finance(("Finance staff"))
node_email_sender(("Email provider"))
node_llm_providers{{"LLM providers"}}

node_frontend_app -->|"routes to"| node_dashboard_ui
node_frontend_app -->|"routes to"| node_prompt_ui
node_frontend_app -->|"routes to"| node_sandbox_ui
node_frontend_app -->|"routes to"| node_review_ui
node_frontend_app -->|"routes to"| node_regression_ui
node_frontend_app -->|"routes to"| node_labeling_ui
node_finance -.->|"uses"| node_frontend_app
node_email_sender -->|"posts messages"| node_email_routes
node_api_app -->|"registers route"| node_email_routes
node_api_app -->|"registers route"| node_sandbox_route
node_email_routes -->|"parses email"| node_email_parser
node_email_routes -->|"submits attachments"| node_ingestion_pipeline
node_sandbox_route -->|"submits document"| node_ingestion_pipeline
node_ingestion_pipeline -->|"stores file"| node_file_storage
node_ingestion_pipeline -->|"extracts data"| node_extractor
node_ingestion_pipeline -->|"validates result"| node_business_rules
node_ingestion_pipeline -->|"records outcome"| node_ingestion_records
node_ingestion_pipeline -->|"syncs pending"| node_excel_sync
node_extractor -->|"builds instructions"| node_envelope
node_extractor -->|"dispatches extraction"| node_providers
node_providers -.->|"requests extraction"| node_llm_providers
node_excel_sync -->|"upserts rows"| node_excel_repository
node_excel_sync -->|"reads pending rows"| node_ingestion_records
node_prompt_routes -->|"builds technical view"| node_envelope
node_document_routes -->|"reads and edits"| node_ingestion_records
node_dashboard_routes -->|"reads metrics"| node_ingestion_records
node_regression_routes -->|"runs suite"| node_regression_runner
node_regression_routes -->|"labels cases"| node_labeling_service
node_regression_runner -->|"scores results"| node_regression_scorer

click node_frontend_app "https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/App.jsx"
click node_dashboard_ui "https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/pages/DashboardPage.jsx"
click node_prompt_ui "https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/pages/HomePage.jsx"
click node_sandbox_ui "https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/pages/SandboxPage.jsx"
click node_review_ui "https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/pages/ReviewPage.jsx"
click node_regression_ui "https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/pages/RegressionPage.jsx"
click node_labeling_ui "https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/pages/LabelingPage.jsx"
click node_api_app "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/main.py"
click node_email_routes "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/api/routes/email.py"
click node_sandbox_route "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/api/routes/ingestion.py"
click node_email_parser "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/email_parser.py"
click node_file_storage "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/file_storage.py"
click node_ingestion_pipeline "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/ingestion_pipeline.py"
click node_extractor "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/extraction/extractor.py"
click node_envelope "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/extraction/system_envelope.py"
click node_providers "https://github.com/guyc21/mailtoexcelautomation/tree/main/backend/services/extraction/providers"
click node_business_rules "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/validation/business_rules.py"
click node_database "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/database.py"
click node_ingestion_records "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/models/ingestion.py"
click node_excel_sync "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/excel_sync.py"
click node_excel_repository "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/repositories/excel_repository.py"
click node_prompt_routes "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/api/routes/prompts.py"
click node_document_routes "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/api/routes/documents.py"
click node_dashboard_routes "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/api/routes/dashboard.py"
click node_regression_routes "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/api/routes/regression.py"
click node_regression_runner "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/regression/runner.py"
click node_regression_scorer "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/regression/scorer.py"
click node_labeling_service "https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/regression/labeling.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_frontend_app,node_dashboard_ui,node_prompt_ui,node_sandbox_ui,node_review_ui,node_regression_ui,node_labeling_ui,node_prompt_routes,node_document_routes,node_dashboard_routes toneBlue
class node_api_app,node_email_routes,node_sandbox_route,node_email_parser,node_file_storage,node_ingestion_pipeline toneAmber
class node_extractor,node_envelope,node_providers,node_business_rules toneMint
class node_database,node_ingestion_records,node_excel_sync,node_excel_repository toneRose
class node_regression_routes,node_regression_runner,node_regression_scorer,node_labeling_service,node_finance,node_email_sender,node_llm_providers toneIndigo
```

## Components

### Backoffice UI

- [Backoffice app](https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Dashboard](https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/pages/DashboardPage.jsx): `frontend/src/pages/DashboardPage.jsx`
- [Prompt management](https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/pages/HomePage.jsx): `frontend/src/pages/HomePage.jsx`
- [Sandbox](https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/pages/SandboxPage.jsx): `frontend/src/pages/SandboxPage.jsx`
- [Document review](https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/pages/ReviewPage.jsx): `frontend/src/pages/ReviewPage.jsx`
- [Regression testing](https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/pages/RegressionPage.jsx): `frontend/src/pages/RegressionPage.jsx`
- [Ground-truth labeling](https://github.com/guyc21/mailtoexcelautomation/blob/main/frontend/src/pages/LabelingPage.jsx): `frontend/src/pages/LabelingPage.jsx`
- [Prompt endpoints](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/api/routes/prompts.py): `backend/api/routes/prompts.py`
- [Review endpoints](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/api/routes/documents.py): `backend/api/routes/documents.py`
- [Dashboard endpoints](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/api/routes/dashboard.py): `backend/api/routes/dashboard.py`

### Document Intake

- [FastAPI application](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/main.py): `backend/main.py`
- [Email endpoints](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/api/routes/email.py): `backend/api/routes/email.py`
- [Sandbox upload](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/api/routes/ingestion.py): `backend/api/routes/ingestion.py`
- [Email parsing](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/email_parser.py): `backend/services/email_parser.py`
- [File storage](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/file_storage.py): `backend/services/file_storage.py`
- [Ingestion orchestrator](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/ingestion_pipeline.py): `backend/services/ingestion_pipeline.py`

### Extraction and Validation

- [Document extractor](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/extraction/extractor.py): `backend/services/extraction/extractor.py`
- [System envelope](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/extraction/system_envelope.py): `backend/services/extraction/system_envelope.py`
- [Provider adapters](https://github.com/guyc21/mailtoexcelautomation/tree/main/backend/services/extraction/providers): `backend/services/extraction/providers`
- [Business validation](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/validation/business_rules.py): `backend/services/validation/business_rules.py`

### Audit and Excel

- [Operational database](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/database.py): `backend/database.py`
- [Ingestion audit records](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/models/ingestion.py): `backend/models/ingestion.py`
- [Workbook synchronization](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/excel_sync.py): `backend/services/excel_sync.py`
- [Excel workbook](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/repositories/excel_repository.py): `backend/repositories/excel_repository.py`

### Regression Suite

- [Regression endpoints](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/api/routes/regression.py): `backend/api/routes/regression.py`
- [Regression runner](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/regression/runner.py): `backend/services/regression/runner.py`
- [Regression scorer](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/regression/scorer.py): `backend/services/regression/scorer.py`
- [Labeling service](https://github.com/guyc21/mailtoexcelautomation/blob/main/backend/services/regression/labeling.py): `backend/services/regression/labeling.py`

### Other components

- **Finance staff**
- **Email provider**
- **LLM providers**

## Connections

- Backoffice app → Dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Backoffice app → Prompt management: routes to (evidence: `frontend/src/App.jsx`)
- Backoffice app → Sandbox: routes to (evidence: `frontend/src/App.jsx`)
- Backoffice app → Document review: routes to (evidence: `frontend/src/App.jsx`)
- Backoffice app → Regression testing: routes to (evidence: `frontend/src/App.jsx`)
- Backoffice app → Ground-truth labeling: routes to (evidence: `frontend/src/App.jsx`)
- Finance staff → Backoffice app: uses
- Email provider → Email endpoints: posts messages
- FastAPI application → Email endpoints: registers route (evidence: `backend/main.py`)
- FastAPI application → Sandbox upload: registers route (evidence: `backend/main.py`)
- Email endpoints → Email parsing: parses email (evidence: `backend/api/routes/email.py`)
- Email endpoints → Ingestion orchestrator: submits attachments (evidence: `backend/api/routes/email.py`)
- Sandbox upload → Ingestion orchestrator: submits document (evidence: `backend/api/routes/ingestion.py`)
- Ingestion orchestrator → File storage: stores file (evidence: `backend/services/ingestion_pipeline.py`)
- Ingestion orchestrator → Document extractor: extracts data (evidence: `backend/services/ingestion_pipeline.py`)
- Ingestion orchestrator → Business validation: validates result (evidence: `backend/services/ingestion_pipeline.py`)
- Ingestion orchestrator → Ingestion audit records: records outcome (evidence: `backend/services/ingestion_pipeline.py`)
- Ingestion orchestrator → Workbook synchronization: syncs pending (evidence: `backend/services/ingestion_pipeline.py`)
- Document extractor → System envelope: builds instructions (evidence: `backend/services/extraction/extractor.py`)
- Document extractor → Provider adapters: dispatches extraction (evidence: `backend/services/extraction/extractor.py`)
- Provider adapters → LLM providers: requests extraction
- Workbook synchronization → Excel workbook: upserts rows (evidence: `backend/services/excel_sync.py`)
- Workbook synchronization → Ingestion audit records: reads pending rows (evidence: `backend/services/excel_sync.py`)
- Prompt endpoints → System envelope: builds technical view (evidence: `backend/api/routes/prompts.py`)
- Review endpoints → Ingestion audit records: reads and edits (evidence: `backend/api/routes/documents.py`)
- Dashboard endpoints → Ingestion audit records: reads metrics (evidence: `backend/api/routes/dashboard.py`)
- Regression endpoints → Regression runner: runs suite (evidence: `backend/api/routes/regression.py`)
- Regression endpoints → Labeling service: labels cases (evidence: `backend/api/routes/regression.py`)
- Regression runner → Regression scorer: scores results
