# at2345/challenge_cto architecture

> Architecture diagram of the GitHub repository at2345/challenge_cto, 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/at2345/challenge_cto
- Repository: https://github.com/at2345/challenge_cto

## Overview

The product is a local invoice-to-booking MVP: users upload PDFs, review extracted fields and governance results, correct yellow cases, and inspect a proposed booking. The backend orchestrates text extraction, privacy handling, deterministic or optional semantic field extraction, rule evaluation, and proposal generation, with MongoDB persistence and audit logging. The frontend exposes this workflow and PDF preview. Main pipeline and API relationships are supported by the sampled excerpts; optional LLM wiring and broader UI capabilities are also documented in the README.

Main entry points: [`backend/src/main.py`](https://github.com/at2345/challenge_cto/blob/main/backend/src/main.py) (Invoice API), [`frontend/src/App.tsx`](https://github.com/at2345/challenge_cto/blob/main/frontend/src/App.tsx) (Workflow UI), [`frontend/src/services/api.ts`](https://github.com/at2345/challenge_cto/blob/main/frontend/src/services/api.ts) (API client), [`backend/src/rules/engine.py`](https://github.com/at2345/challenge_cto/blob/main/backend/src/rules/engine.py) (Rule evaluator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Review interface"]
  node_app["Workflow UI<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_invoice_selector["Invoice selector"]
  node_pdf_preview["PDF preview<br/>[PdfPreview.tsx]"]
  node_field_form["Field editor"]
  node_validation_view["Validation results"]
  node_traffic_badge["Traffic status"]
  node_proposal_view["Booking display"]
end

subgraph group_pipeline["Invoice processing"]
  node_api["Invoice API<br/>[main.py]"]
  node_pdf_loader["PDF text loader<br/>[pdf_loader.py]"]
  node_privacy["PII pseudonymizer<br/>[anonymizer.py]"]
  node_regex_extract["Regex extraction<br/>[field_extractor.py]"]
  node_llm_extract["Optional LLM extraction<br/>[llm_extractor.py]"]
end

subgraph group_governance["Rules and booking"]
  node_rules["Rule evaluator<br/>[engine.py]"]
  node_validators["Validation rules<br/>[validators.py]"]
  node_account_suggester["Account suggestion"]
  node_proposal["Proposal builder"]
end

subgraph group_state["Data and privacy"]
  node_master_data["Master data<br/>[master_data.py]"]
  node_database["Mongo access<br/>[database.py]"]
  node_memory_vault["Memory vault<br/>[memory_vault.py]"]
end

node_user(("User"))
node_mongo[("MongoDB")]
node_llm_service["OpenAI-compatible model"]

node_user -->|"uploads and reviews"| node_app
node_app -->|"renders"| node_invoice_selector
node_app -->|"renders"| node_pdf_preview
node_app -->|"renders"| node_field_form
node_app -->|"renders"| node_validation_view
node_app -->|"renders"| node_traffic_badge
node_app -->|"renders"| node_proposal_view
node_app -->|"requests"| node_api_client
node_api_client -->|"calls API"| node_api
node_api -->|"extracts PDF text"| node_pdf_loader
node_api -->|"pseudonymizes text"| node_privacy
node_api -->|"fallback extraction"| node_regex_extract
node_api -.->|"optional extraction"| node_llm_extract
node_api -->|"evaluates fields"| node_rules
node_api -->|"builds proposal"| node_proposal
node_api -->|"reads and writes"| node_database
node_api -->|"uses fallback data"| node_master_data
node_rules -->|"runs checks"| node_validators
node_rules -->|"suggests account"| node_account_suggester
node_privacy -->|"retains mappings"| node_memory_vault
node_llm_extract -.->|"sends sanitized text"| node_llm_service
node_database -->|"queries and stores"| node_mongo
node_api_client -->|"fetches PDF"| node_api

click node_app "https://github.com/at2345/challenge_cto/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/at2345/challenge_cto/blob/main/frontend/src/services/api.ts"
click node_invoice_selector "https://github.com/at2345/challenge_cto/blob/main/frontend/src/components/InvoiceSelector.tsx"
click node_pdf_preview "https://github.com/at2345/challenge_cto/blob/main/frontend/src/components/PdfPreview.tsx"
click node_field_form "https://github.com/at2345/challenge_cto/blob/main/frontend/src/components/ExtractedDataForm.tsx"
click node_validation_view "https://github.com/at2345/challenge_cto/blob/main/frontend/src/components/ValidationResults.tsx"
click node_traffic_badge "https://github.com/at2345/challenge_cto/blob/main/frontend/src/components/TrafficLightBadge.tsx"
click node_proposal_view "https://github.com/at2345/challenge_cto/blob/main/frontend/src/components/BookingProposalTable.tsx"
click node_api "https://github.com/at2345/challenge_cto/blob/main/backend/src/main.py"
click node_pdf_loader "https://github.com/at2345/challenge_cto/blob/main/backend/src/extraction/pdf_loader.py"
click node_privacy "https://github.com/at2345/challenge_cto/blob/main/backend/src/security/anonymizer.py"
click node_regex_extract "https://github.com/at2345/challenge_cto/blob/main/backend/src/extraction/field_extractor.py"
click node_llm_extract "https://github.com/at2345/challenge_cto/blob/main/backend/src/extraction/llm_extractor.py"
click node_rules "https://github.com/at2345/challenge_cto/blob/main/backend/src/rules/engine.py"
click node_validators "https://github.com/at2345/challenge_cto/blob/main/backend/src/rules/validators.py"
click node_account_suggester "https://github.com/at2345/challenge_cto/blob/main/backend/src/rules/account_suggester.py"
click node_proposal "https://github.com/at2345/challenge_cto/blob/main/backend/src/accounting/proposal_builder.py"
click node_master_data "https://github.com/at2345/challenge_cto/blob/main/backend/src/master_data.py"
click node_database "https://github.com/at2345/challenge_cto/blob/main/backend/src/database.py"
click node_memory_vault "https://github.com/at2345/challenge_cto/blob/main/backend/src/security/memory_vault.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_api_client,node_invoice_selector,node_pdf_preview,node_field_form,node_validation_view,node_traffic_badge,node_proposal_view,node_user toneBlue
class node_api,node_pdf_loader,node_privacy,node_regex_extract,node_llm_extract,node_mongo toneAmber
class node_rules,node_validators,node_account_suggester,node_proposal toneMint
class node_master_data,node_database,node_memory_vault toneRose
class node_llm_service toneIndigo
```

## Components

### Review interface

- [Workflow UI](https://github.com/at2345/challenge_cto/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/at2345/challenge_cto/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Invoice selector](https://github.com/at2345/challenge_cto/blob/main/frontend/src/components/InvoiceSelector.tsx): `frontend/src/components/InvoiceSelector.tsx`
- [PDF preview](https://github.com/at2345/challenge_cto/blob/main/frontend/src/components/PdfPreview.tsx): `frontend/src/components/PdfPreview.tsx`
- [Field editor](https://github.com/at2345/challenge_cto/blob/main/frontend/src/components/ExtractedDataForm.tsx): `frontend/src/components/ExtractedDataForm.tsx`
- [Validation results](https://github.com/at2345/challenge_cto/blob/main/frontend/src/components/ValidationResults.tsx): `frontend/src/components/ValidationResults.tsx`
- [Traffic status](https://github.com/at2345/challenge_cto/blob/main/frontend/src/components/TrafficLightBadge.tsx): `frontend/src/components/TrafficLightBadge.tsx`
- [Booking display](https://github.com/at2345/challenge_cto/blob/main/frontend/src/components/BookingProposalTable.tsx): `frontend/src/components/BookingProposalTable.tsx`

### Invoice processing

- [Invoice API](https://github.com/at2345/challenge_cto/blob/main/backend/src/main.py): `backend/src/main.py`
- [PDF text loader](https://github.com/at2345/challenge_cto/blob/main/backend/src/extraction/pdf_loader.py): `backend/src/extraction/pdf_loader.py`
- [PII pseudonymizer](https://github.com/at2345/challenge_cto/blob/main/backend/src/security/anonymizer.py): `backend/src/security/anonymizer.py`
- [Regex extraction](https://github.com/at2345/challenge_cto/blob/main/backend/src/extraction/field_extractor.py): `backend/src/extraction/field_extractor.py`
- [Optional LLM extraction](https://github.com/at2345/challenge_cto/blob/main/backend/src/extraction/llm_extractor.py): `backend/src/extraction/llm_extractor.py`

### Rules and booking

- [Rule evaluator](https://github.com/at2345/challenge_cto/blob/main/backend/src/rules/engine.py): `backend/src/rules/engine.py`
- [Validation rules](https://github.com/at2345/challenge_cto/blob/main/backend/src/rules/validators.py): `backend/src/rules/validators.py`
- [Account suggestion](https://github.com/at2345/challenge_cto/blob/main/backend/src/rules/account_suggester.py): `backend/src/rules/account_suggester.py`
- [Proposal builder](https://github.com/at2345/challenge_cto/blob/main/backend/src/accounting/proposal_builder.py): `backend/src/accounting/proposal_builder.py`

### Data and privacy

- [Master data](https://github.com/at2345/challenge_cto/blob/main/backend/src/master_data.py): `backend/src/master_data.py`
- [Mongo access](https://github.com/at2345/challenge_cto/blob/main/backend/src/database.py): `backend/src/database.py`
- [Memory vault](https://github.com/at2345/challenge_cto/blob/main/backend/src/security/memory_vault.py): `backend/src/security/memory_vault.py`

### Other components

- **User**
- **MongoDB**
- **OpenAI-compatible model**

## Connections

- User → Workflow UI: uploads and reviews
- Workflow UI → Invoice selector: renders
- Workflow UI → PDF preview: renders
- Workflow UI → Field editor: renders
- Workflow UI → Validation results: renders
- Workflow UI → Traffic status: renders
- Workflow UI → Booking display: renders
- Workflow UI → API client: requests
- API client → Invoice API: calls API
- Invoice API → PDF text loader: extracts PDF text
- Invoice API → PII pseudonymizer: pseudonymizes text
- Invoice API → Regex extraction: fallback extraction
- Invoice API → Optional LLM extraction: optional extraction
- Invoice API → Rule evaluator: evaluates fields
- Invoice API → Proposal builder: builds proposal
- Invoice API → Mongo access: reads and writes
- Invoice API → Master data: uses fallback data
- Rule evaluator → Validation rules: runs checks
- Rule evaluator → Account suggestion: suggests account
- PII pseudonymizer → Memory vault: retains mappings
- Optional LLM extraction → OpenAI-compatible model: sends sanitized text
- Mongo access → MongoDB: queries and stores
- API client → Invoice API: fetches PDF