# yhuir/fin-ops-platform architecture

> Architecture diagram of the GitHub repository yhuir/fin-ops-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yhuir/fin-ops-platform
- Repository: https://github.com/yhuir/fin-ops-platform

## Overview

fin-ops-platform is a financial operations application centered on bank-to-enterprise reconciliation. Users enter through the React application and use import workflows, a reconciliation workbench, and related finance pages; backend routes expose business operations, services implement domain behavior, and PostgreSQL stores production state and business facts. Major product branches include bank transactions, invoices, OA payments, ETC, tax offsets, turnover ledgers, cost statistics, cash, and background jobs. The README documents PostgreSQL as the sole production app read/write store and OA MongoDB as read-only via an adapter. Several service and route connections are inferred from module names and documented capabilities; unsampled wiring is not expanded.

Main entry points: [`backend/src/fin_ops_platform/app`](https://github.com/yhuir/fin-ops-platform/tree/main/backend/src/fin_ops_platform/app) (Backend HTTP API), [`backend/src/fin_ops_platform/services/postgres_repositories`](https://github.com/yhuir/fin-ops-platform/tree/main/backend/src/fin_ops_platform/services/postgres_repositories) (PostgreSQL repositories), [`web/src/app/App.tsx`](https://github.com/yhuir/fin-ops-platform/blob/main/web/src/app/App.tsx) (React application), [`backend/src/fin_ops_platform/services/workbench_query_service.py`](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/workbench_query_service.py) (Reconciliation workbench)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client application"]
  node_web_app["React application<br/>[App.tsx]"]
  node_import_routes["Import navigation<br/>[importRoutes.ts]"]
  node_page_session["Page session state"]
end

subgraph group_operations["Reconciliation operations"]
  node_http_api["Backend HTTP API"]
  node_imports["Data imports"]
  node_workbench["Reconciliation workbench"]
  node_bank_ops["Bank transactions"]
  node_background_jobs["Background jobs"]
end

subgraph group_finance["Finance domains"]
  node_invoice_usage["Input invoice usage"]
  node_output_collections["Output collections"]
  node_oa_payments["OA pending payments"]
  node_etc["ETC operations<br/>[etc_service.py]"]
  node_tax["Tax offsets"]
  node_turnover["Turnover ledger"]
  node_cost_statistics["Cost statistics"]
  node_cash["Cash operations<br/>[cash_service.py]"]
end

subgraph group_platform["Persistence and integrations"]
  node_postgres_repositories["PostgreSQL repositories"]
  node_postgres[("PostgreSQL")]
  node_oa_adapter["OA adapter<br/>[oa_adapter.py]"]
end

node_finance_user(("Finance user"))
node_oa_system["OA system"]

node_finance_user -->|"uses"| node_web_app
node_web_app -->|"navigates"| node_import_routes
node_web_app -->|"persists page state"| node_page_session
node_web_app -->|"requests operations"| node_http_api
node_http_api -->|"handles imports"| node_imports
node_http_api -->|"serves reconciliation"| node_workbench
node_http_api -->|"serves bank details"| node_bank_ops
node_http_api -->|"serves invoice usage"| node_invoice_usage
node_http_api -->|"serves collections"| node_output_collections
node_http_api -->|"serves payment queries"| node_oa_payments
node_http_api -->|"serves ETC operations"| node_etc
node_http_api -->|"serves tax offsets"| node_tax
node_http_api -->|"serves ledger"| node_turnover
node_http_api -->|"serves statistics"| node_cost_statistics
node_http_api -->|"serves cash operations"| node_cash
node_http_api -->|"dispatches jobs"| node_background_jobs
node_workbench -->|"queries canonical facts"| node_postgres_repositories
node_oa_payments -->|"loads canonical facts"| node_postgres_repositories
node_invoice_usage -->|"loads page facts"| node_postgres_repositories
node_output_collections -->|"loads page facts"| node_postgres_repositories
node_postgres_repositories -->|"reads and writes"| node_postgres
node_oa_adapter -.->|"reads OA data"| node_oa_system

click node_web_app "https://github.com/yhuir/fin-ops-platform/blob/main/web/src/app/App.tsx"
click node_import_routes "https://github.com/yhuir/fin-ops-platform/blob/main/web/src/features/imports/importRoutes.ts"
click node_page_session "https://github.com/yhuir/fin-ops-platform/blob/main/web/src/contexts/pageSessionStorage.ts"
click node_http_api "https://github.com/yhuir/fin-ops-platform/tree/main/backend/src/fin_ops_platform/app"
click node_imports "https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/import_workflow_service.py"
click node_workbench "https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/workbench_query_service.py"
click node_bank_ops "https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/bank_details_service.py"
click node_invoice_usage "https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/input_invoice_usage_canonical_query_service.py"
click node_output_collections "https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/output_invoice_collection_canonical_query_service.py"
click node_oa_payments "https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/oa_pending_payment_query_service.py"
click node_etc "https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/etc_service.py"
click node_tax "https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/tax_offset_service.py"
click node_turnover "https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/turnover_ledger_service.py"
click node_cost_statistics "https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/cost_statistics_query_service.py"
click node_cash "https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/cash_service.py"
click node_background_jobs "https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/background_job_service.py"
click node_postgres_repositories "https://github.com/yhuir/fin-ops-platform/tree/main/backend/src/fin_ops_platform/services/postgres_repositories"
click node_oa_adapter "https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/oa_adapter.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_web_app,node_import_routes,node_page_session,node_finance_user toneBlue
class node_http_api,node_imports,node_workbench,node_bank_ops,node_background_jobs toneAmber
class node_invoice_usage,node_output_collections,node_oa_payments,node_etc,node_tax,node_turnover,node_cost_statistics,node_cash toneMint
class node_postgres_repositories,node_postgres,node_oa_adapter toneRose
class node_oa_system toneIndigo
```

## Components

### Client application

- [React application](https://github.com/yhuir/fin-ops-platform/blob/main/web/src/app/App.tsx): `web/src/app/App.tsx`
- [Import navigation](https://github.com/yhuir/fin-ops-platform/blob/main/web/src/features/imports/importRoutes.ts): `web/src/features/imports/importRoutes.ts`
- [Page session state](https://github.com/yhuir/fin-ops-platform/blob/main/web/src/contexts/pageSessionStorage.ts): `web/src/contexts/pageSessionStorage.ts`

### Reconciliation operations

- [Backend HTTP API](https://github.com/yhuir/fin-ops-platform/tree/main/backend/src/fin_ops_platform/app): `backend/src/fin_ops_platform/app`
- [Data imports](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/import_workflow_service.py): `backend/src/fin_ops_platform/services/import_workflow_service.py`
- [Reconciliation workbench](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/workbench_query_service.py): `backend/src/fin_ops_platform/services/workbench_query_service.py`
- [Bank transactions](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/bank_details_service.py): `backend/src/fin_ops_platform/services/bank_details_service.py`
- [Background jobs](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/background_job_service.py): `backend/src/fin_ops_platform/services/background_job_service.py`

### Finance domains

- [Input invoice usage](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/input_invoice_usage_canonical_query_service.py): `backend/src/fin_ops_platform/services/input_invoice_usage_canonical_query_service.py`
- [Output collections](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/output_invoice_collection_canonical_query_service.py): `backend/src/fin_ops_platform/services/output_invoice_collection_canonical_query_service.py`
- [OA pending payments](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/oa_pending_payment_query_service.py): `backend/src/fin_ops_platform/services/oa_pending_payment_query_service.py`
- [ETC operations](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/etc_service.py): `backend/src/fin_ops_platform/services/etc_service.py`
- [Tax offsets](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/tax_offset_service.py): `backend/src/fin_ops_platform/services/tax_offset_service.py`
- [Turnover ledger](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/turnover_ledger_service.py): `backend/src/fin_ops_platform/services/turnover_ledger_service.py`
- [Cost statistics](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/cost_statistics_query_service.py): `backend/src/fin_ops_platform/services/cost_statistics_query_service.py`
- [Cash operations](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/cash_service.py): `backend/src/fin_ops_platform/services/cash_service.py`

### Persistence and integrations

- [PostgreSQL repositories](https://github.com/yhuir/fin-ops-platform/tree/main/backend/src/fin_ops_platform/services/postgres_repositories): `backend/src/fin_ops_platform/services/postgres_repositories`
- **PostgreSQL**
- [OA adapter](https://github.com/yhuir/fin-ops-platform/blob/main/backend/src/fin_ops_platform/services/oa_adapter.py): `backend/src/fin_ops_platform/services/oa_adapter.py`

### Other components

- **Finance user**
- **OA system**

## Connections

- Finance user → React application: uses
- React application → Import navigation: navigates
- React application → Page session state: persists page state
- React application → Backend HTTP API: requests operations
- Backend HTTP API → Data imports: handles imports
- Backend HTTP API → Reconciliation workbench: serves reconciliation
- Backend HTTP API → Bank transactions: serves bank details
- Backend HTTP API → Input invoice usage: serves invoice usage
- Backend HTTP API → Output collections: serves collections
- Backend HTTP API → OA pending payments: serves payment queries
- Backend HTTP API → ETC operations: serves ETC operations
- Backend HTTP API → Tax offsets: serves tax offsets
- Backend HTTP API → Turnover ledger: serves ledger
- Backend HTTP API → Cost statistics: serves statistics
- Backend HTTP API → Cash operations: serves cash operations
- Backend HTTP API → Background jobs: dispatches jobs
- Reconciliation workbench → PostgreSQL repositories: queries canonical facts
- OA pending payments → PostgreSQL repositories: loads canonical facts
- Input invoice usage → PostgreSQL repositories: loads page facts
- Output collections → PostgreSQL repositories: loads page facts
- PostgreSQL repositories → PostgreSQL: reads and writes
- OA adapter → OA system: reads OA data