# officialpk956-wq/ca_saas architecture

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

- Interactive diagram: https://gitdiagram.com/officialpk956-wq/ca_saas
- Repository: https://github.com/officialpk956-wq/ca_saas

## Overview

GST Helper is a local GST-workpaper demo. Users create a client and period, import and review purchase/statement records, reconcile selected committed versions, inspect evidence and save decisions, then export a workbook. Separate product branches support purchase categorization, sales preparation, and draft worksheet approval. The README documents these capabilities; sampled source and the SOURCE INDEX support the backend ownership links below. Some frontend-to-API wiring and unsampled subsystem internals are not shown, so those links rely on documented behavior rather than inferred calls.

Main entry points: [`backend/gst_copilot/api/main.py`](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/main.py) (HTTP API), [`backend/gst_copilot/db/models.py`](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/db/models.py) (PostgreSQL data), [`backend/gst_copilot/services/import_service.py`](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/services/import_service.py) (Import processing), [`backend/gst_copilot/services/reconciliation_service.py`](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/services/reconciliation_service.py) (Reconciliation service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Web workspace<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_clients["Client setup<br/>[clients.py]"]
end

subgraph group_imports["Import and reconciliation"]
  node_imports_api["Import endpoints<br/>[import_batches.py]"]
  node_import_service["Import processing<br/>[import_service.py]"]
  node_parser["CSV parser<br/>[parser.py]"]
  node_validation["Row validation<br/>[validation.py]"]
  node_reconcile_api["Reconcile endpoint<br/>[reconciliation.py]"]
  node_reconcile_service["Reconciliation service"]
  node_reconcile_engine["Matching engine<br/>[reconciliation.py]"]
end

subgraph group_review["Review and reporting"]
  node_review_api["Review decisions<br/>[resolutions.py]"]
  node_review_service["Evidence projections<br/>[review_service.py]"]
  node_export_api["Export endpoint<br/>[exports.py]"]
  node_export_service["Workbook export<br/>[export_service.py]"]
end

subgraph group_extensions["Preparation extensions"]
  node_categories["Category review<br/>[categories.py]"]
  node_categorizer["Category suggestions<br/>[categorization.py]"]
  node_sales["Sales preparation<br/>[sales.py]"]
  node_worksheet["Draft worksheet<br/>[worksheet.py]"]
  node_assistant["GST assistant<br/>[assist.py]"]
end

subgraph group_persistence["Persistence and access"]
  node_api["HTTP API<br/>[main.py]"]
  node_database[("PostgreSQL data<br/>[models.py]")]
  node_db_session["Database sessions<br/>[database.py]"]
end

node_user(("GST reviewer"))

node_user -->|"uses"| node_frontend
node_frontend -.->|"requests"| node_api_client
node_api_client -.->|"calls API"| node_api
node_api -->|"routes"| node_clients
node_api -->|"routes"| node_imports_api
node_api -->|"routes"| node_reconcile_api
node_api -->|"routes"| node_review_api
node_api -->|"routes"| node_export_api
node_api -->|"routes"| node_categories
node_api -->|"routes"| node_sales
node_api -->|"routes"| node_worksheet
node_api -->|"routes"| node_assistant
node_imports_api -->|"processes uploads"| node_import_service
node_import_service -->|"parses rows"| node_parser
node_import_service -->|"validates rows"| node_validation
node_reconcile_api -->|"runs reconciliation"| node_reconcile_service
node_reconcile_service -->|"matches records"| node_reconcile_engine
node_review_api -.->|"projects evidence"| node_review_service
node_export_api -->|"builds workbook"| node_export_service
node_categories -->|"requests suggestions"| node_categorizer
node_clients -->|"reads and writes"| node_database
node_import_service -->|"persists imports"| node_database
node_reconcile_service -->|"persists runs"| node_database
node_review_service -->|"reads history"| node_database
node_export_service -.->|"reads records"| node_database
node_db_session -->|"connects sessions"| node_database
node_api -.->|"provides sessions"| node_db_session
node_user -->|"reviews categories"| node_categories
node_user -->|"prepares sales"| node_sales
node_user -->|"prepares drafts"| node_worksheet
node_user -.->|"asks for help"| node_assistant

click node_frontend "https://github.com/officialpk956-wq/ca_saas/blob/main/frontend/app/periods/%5Bperiod_id%5D/workspace/page.tsx"
click node_api_client "https://github.com/officialpk956-wq/ca_saas/blob/main/frontend/lib/api.ts"
click node_api "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/main.py"
click node_clients "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/clients.py"
click node_imports_api "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/import_batches.py"
click node_import_service "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/services/import_service.py"
click node_parser "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/parser.py"
click node_validation "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/validation.py"
click node_reconcile_api "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/reconciliation.py"
click node_reconcile_service "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/services/reconciliation_service.py"
click node_reconcile_engine "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/reconciliation.py"
click node_review_api "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/resolutions.py"
click node_review_service "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/services/review_service.py"
click node_export_api "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/exports.py"
click node_export_service "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/services/export_service.py"
click node_categories "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/categories.py"
click node_categorizer "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/model_gateway/categorization.py"
click node_sales "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/sales.py"
click node_worksheet "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/worksheet.py"
click node_assistant "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/assist.py"
click node_database "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/db/models.py"
click node_db_session "https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/db/database.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,node_api_client,node_clients,node_user toneBlue
class node_imports_api,node_import_service,node_parser,node_validation,node_reconcile_api,node_reconcile_service,node_reconcile_engine toneAmber
class node_review_api,node_review_service,node_export_api,node_export_service toneMint
class node_categories,node_categorizer,node_sales,node_worksheet,node_assistant toneRose
class node_api,node_database,node_db_session toneIndigo
```

## Components

### User experience

- [Web workspace](https://github.com/officialpk956-wq/ca_saas/blob/main/frontend/app/periods/%5Bperiod_id%5D/workspace/page.tsx): `frontend/app/periods/[period_id]/workspace/page.tsx`
- [API client](https://github.com/officialpk956-wq/ca_saas/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Client setup](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/clients.py): `backend/gst_copilot/api/routers/clients.py`

### Import and reconciliation

- [Import endpoints](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/import_batches.py): `backend/gst_copilot/api/routers/import_batches.py`
- [Import processing](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/services/import_service.py): `backend/gst_copilot/services/import_service.py`
- [CSV parser](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/parser.py): `backend/gst_copilot/parser.py`
- [Row validation](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/validation.py): `backend/gst_copilot/validation.py`
- [Reconcile endpoint](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/reconciliation.py): `backend/gst_copilot/api/routers/reconciliation.py`
- [Reconciliation service](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/services/reconciliation_service.py): `backend/gst_copilot/services/reconciliation_service.py`
- [Matching engine](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/reconciliation.py): `backend/gst_copilot/reconciliation.py`

### Review and reporting

- [Review decisions](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/resolutions.py): `backend/gst_copilot/api/routers/resolutions.py`
- [Evidence projections](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/services/review_service.py): `backend/gst_copilot/services/review_service.py`
- [Export endpoint](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/exports.py): `backend/gst_copilot/api/routers/exports.py`
- [Workbook export](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/services/export_service.py): `backend/gst_copilot/services/export_service.py`

### Preparation extensions

- [Category review](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/categories.py): `backend/gst_copilot/api/routers/categories.py`
- [Category suggestions](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/model_gateway/categorization.py): `backend/gst_copilot/model_gateway/categorization.py`
- [Sales preparation](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/sales.py): `backend/gst_copilot/api/routers/sales.py`
- [Draft worksheet](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/worksheet.py): `backend/gst_copilot/api/routers/worksheet.py`
- [GST assistant](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/routers/assist.py): `backend/gst_copilot/api/routers/assist.py`

### Persistence and access

- [HTTP API](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/api/main.py): `backend/gst_copilot/api/main.py`
- [PostgreSQL data](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/db/models.py): `backend/gst_copilot/db/models.py`
- [Database sessions](https://github.com/officialpk956-wq/ca_saas/blob/main/backend/gst_copilot/db/database.py): `backend/gst_copilot/db/database.py`

### Other components

- **GST reviewer**

## Connections

- GST reviewer → Web workspace: uses (evidence: `README.md`)
- Web workspace → API client: requests
- API client → HTTP API: calls API
- HTTP API → Client setup: routes (evidence: `backend/gst_copilot/api/main.py`)
- HTTP API → Import endpoints: routes (evidence: `backend/gst_copilot/api/main.py`)
- HTTP API → Reconcile endpoint: routes (evidence: `backend/gst_copilot/api/main.py`)
- HTTP API → Review decisions: routes (evidence: `backend/gst_copilot/api/main.py`)
- HTTP API → Export endpoint: routes (evidence: `backend/gst_copilot/api/main.py`)
- HTTP API → Category review: routes (evidence: `backend/gst_copilot/api/main.py`)
- HTTP API → Sales preparation: routes (evidence: `backend/gst_copilot/api/main.py`)
- HTTP API → Draft worksheet: routes (evidence: `backend/gst_copilot/api/main.py`)
- HTTP API → GST assistant: routes (evidence: `backend/gst_copilot/api/main.py`)
- Import endpoints → Import processing: processes uploads (evidence: `backend/gst_copilot/api/routers/import_batches.py`)
- Import processing → CSV parser: parses rows (evidence: `backend/gst_copilot/services/import_service.py`)
- Import processing → Row validation: validates rows (evidence: `backend/gst_copilot/services/import_service.py`)
- Reconcile endpoint → Reconciliation service: runs reconciliation (evidence: `backend/gst_copilot/api/routers/reconciliation.py`)
- Reconciliation service → Matching engine: matches records (evidence: `backend/gst_copilot/services/reconciliation_service.py`)
- Review decisions → Evidence projections: projects evidence
- Export endpoint → Workbook export: builds workbook (evidence: `backend/gst_copilot/api/routers/exports.py`)
- Category review → Category suggestions: requests suggestions (evidence: `backend/gst_copilot/api/routers/categories.py`)
- Client setup → PostgreSQL data: reads and writes (evidence: `backend/gst_copilot/api/routers/clients.py`)
- Import processing → PostgreSQL data: persists imports (evidence: `backend/gst_copilot/services/import_service.py`)
- Reconciliation service → PostgreSQL data: persists runs (evidence: `backend/gst_copilot/services/reconciliation_service.py`)
- Evidence projections → PostgreSQL data: reads history (evidence: `backend/gst_copilot/services/review_service.py`)
- Workbook export → PostgreSQL data: reads records
- Database sessions → PostgreSQL data: connects sessions (evidence: `backend/gst_copilot/db/database.py`)
- HTTP API → Database sessions: provides sessions
- GST reviewer → Category review: reviews categories (evidence: `README.md`)
- GST reviewer → Sales preparation: prepares sales (evidence: `README.md`)
- GST reviewer → Draft worksheet: prepares drafts (evidence: `README.md`)
- GST reviewer → GST assistant: asks for help
