# yixun06/invoice-statement-gathering-system architecture

> Architecture diagram of the GitHub repository yixun06/invoice-statement-gathering-system, 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/yixun06/invoice-statement-gathering-system
- Repository: https://github.com/yixun06/invoice-statement-gathering-system

## Overview

Invoice Analytics System V1 is a Streamlit workflow for importing mixed-platform invoice PDFs, parsing and reviewing their order and product facts, then viewing and exporting batch analytics. A separate weekly-statement workflow stages Shopee workbook data for reconciliation; the repository also contains a historical-invoice storage subsystem. The README documents platform tabs, batch archives, duplicate handling, and review reports. Sampled excerpts do not expose every app-level call, so uncertain wiring—especially historical storage—is left unconnected.

Main entry points: [`app.py`](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/app.py) (Streamlit application), [`src/invoice_app/services/batch_service.py`](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/services/batch_service.py) (Batch processing), [`src/invoice_app/ui/weekly_billing.py`](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/ui/weekly_billing.py) (Weekly billing UI), [`src/invoice_app/ui/data_import.py`](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/ui/data_import.py) (Import wizard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Import and parsing"]
  node_app["Streamlit application<br/>[app.py]"]
  node_import_ui["Import wizard<br/>[data_import.py]"]
  node_batch["Batch processing<br/>[batch_service.py]"]
  node_detector["Platform detection<br/>[detector.py]"]
  node_parsers["Invoice parsers"]
  node_pdfdoc["PDF extraction<br/>[pdf_document.py]"]
  node_auth["Authentication<br/>[auth_service.py]"]
end

subgraph group_review["Validation and review"]
  node_review_policy["Shopee review policy"]
end

subgraph group_report["Analytics and export"]
  node_analytics["Invoice analytics<br/>[analytics.py]"]
  node_exporter["Excel export<br/>[exporter.py]"]
end

subgraph group_weekly["Weekly settlement"]
  node_weekly_ui["Weekly billing UI<br/>[weekly_billing.py]"]
  node_weekly_service["Statement staging"]
  node_weekly_parser["Statement parser"]
  node_settlement_lab["Settlement test lab"]
end

subgraph group_history["Historical invoices"]
  node_repository_contract["Invoice repository"]
  node_sheets_adapter["Sheets adapter"]
end

node_user(("Invoice operator"))
node_pdfs["Invoice PDFs"]
node_workbook["Weekly workbook"]
node_sheets[("Google Sheets")]

node_user -->|"uses"| node_app
node_user -->|"selects source"| node_import_ui
node_pdfs -->|"uploads"| node_import_ui
node_workbook -->|"uploads"| node_weekly_ui
node_app -->|"authenticates"| node_auth
node_app -->|"processes batch"| node_batch
node_app -->|"builds dashboards"| node_analytics
node_app -->|"exports reports"| node_exporter
node_import_ui -->|"stages imports"| node_batch
node_batch -->|"extracts text"| node_pdfdoc
node_batch -->|"detects platform"| node_detector
node_batch -->|"dispatches parsing"| node_parsers
node_parsers -->|"checks Shopee"| node_review_policy
node_weekly_ui -->|"stages statement"| node_weekly_service
node_weekly_service -->|"parses workbook"| node_weekly_parser
node_weekly_ui -->|"offers testing"| node_settlement_lab
node_sheets_adapter -.->|"reads and writes"| node_sheets
node_sheets_adapter -->|"implements contract"| node_repository_contract

click node_app "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/app.py"
click node_import_ui "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/ui/data_import.py"
click node_batch "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/services/batch_service.py"
click node_detector "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/detector.py"
click node_parsers "https://github.com/yixun06/invoice-statement-gathering-system/tree/main/src/invoice_app/parsers"
click node_pdfdoc "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/pdf_document.py"
click node_auth "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/services/auth_service.py"
click node_review_policy "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/parsers/shopee_review_policy.py"
click node_analytics "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/services/analytics.py"
click node_exporter "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/services/exporter.py"
click node_weekly_ui "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/ui/weekly_billing.py"
click node_weekly_service "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/services/shopee_weekly_statement_service.py"
click node_weekly_parser "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/parsers/shopee_weekly_statement_parser.py"
click node_settlement_lab "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/ui/settlement_test_lab.py"
click node_repository_contract "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/repositories/historical_invoice_repository.py"
click node_sheets_adapter "https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/repositories/google_sheets_historical_invoice_repository.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_import_ui,node_batch,node_detector,node_parsers,node_pdfdoc,node_auth toneBlue
class node_review_policy,node_sheets toneAmber
class node_analytics,node_exporter toneMint
class node_weekly_ui,node_weekly_service,node_weekly_parser,node_settlement_lab toneRose
class node_repository_contract,node_sheets_adapter,node_user,node_pdfs,node_workbook toneIndigo
```

## Components

### Import and parsing

- [Streamlit application](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/app.py): `app.py`
- [Import wizard](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/ui/data_import.py): `src/invoice_app/ui/data_import.py`
- [Batch processing](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/services/batch_service.py): `src/invoice_app/services/batch_service.py`
- [Platform detection](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/detector.py): `src/invoice_app/detector.py`
- [Invoice parsers](https://github.com/yixun06/invoice-statement-gathering-system/tree/main/src/invoice_app/parsers): `src/invoice_app/parsers`
- [PDF extraction](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/pdf_document.py): `src/invoice_app/pdf_document.py`
- [Authentication](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/services/auth_service.py): `src/invoice_app/services/auth_service.py`

### Validation and review

- [Shopee review policy](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/parsers/shopee_review_policy.py): `src/invoice_app/parsers/shopee_review_policy.py`

### Analytics and export

- [Invoice analytics](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/services/analytics.py): `src/invoice_app/services/analytics.py`
- [Excel export](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/services/exporter.py): `src/invoice_app/services/exporter.py`

### Weekly settlement

- [Weekly billing UI](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/ui/weekly_billing.py): `src/invoice_app/ui/weekly_billing.py`
- [Statement staging](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/services/shopee_weekly_statement_service.py): `src/invoice_app/services/shopee_weekly_statement_service.py`
- [Statement parser](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/parsers/shopee_weekly_statement_parser.py): `src/invoice_app/parsers/shopee_weekly_statement_parser.py`
- [Settlement test lab](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/ui/settlement_test_lab.py): `src/invoice_app/ui/settlement_test_lab.py`

### Historical invoices

- [Invoice repository](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/repositories/historical_invoice_repository.py): `src/invoice_app/repositories/historical_invoice_repository.py`
- [Sheets adapter](https://github.com/yixun06/invoice-statement-gathering-system/blob/main/src/invoice_app/repositories/google_sheets_historical_invoice_repository.py): `src/invoice_app/repositories/google_sheets_historical_invoice_repository.py`

### Other components

- **Invoice operator**
- **Invoice PDFs**
- **Weekly workbook**
- **Google Sheets**

## Connections

- Invoice operator → Streamlit application: uses
- Invoice operator → Import wizard: selects source
- Invoice PDFs → Import wizard: uploads
- Weekly workbook → Weekly billing UI: uploads
- Streamlit application → Authentication: authenticates
- Streamlit application → Batch processing: processes batch
- Streamlit application → Invoice analytics: builds dashboards
- Streamlit application → Excel export: exports reports
- Import wizard → Batch processing: stages imports
- Batch processing → PDF extraction: extracts text
- Batch processing → Platform detection: detects platform
- Batch processing → Invoice parsers: dispatches parsing
- Invoice parsers → Shopee review policy: checks Shopee
- Weekly billing UI → Statement staging: stages statement
- Statement staging → Statement parser: parses workbook
- Weekly billing UI → Settlement test lab: offers testing
- Sheets adapter → Google Sheets: reads and writes
- Sheets adapter → Invoice repository: implements contract