# eklakh-ai-engineer/taxtrace architecture

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

- Interactive diagram: https://gitdiagram.com/eklakh-ai-engineer/taxtrace
- Repository: https://github.com/eklakh-ai-engineer/taxtrace

## Overview

TaxTrace is a controlled-pilot compliance platform for CA firms. Its primary workflow takes purchase-register and GSTR-2B data through normalization and deterministic reconciliation, then supports evidence-backed exception review and audit. Separate branches cover notice extraction and drafting, knowledge retrieval, tasks/dashboard follow-up, and chat/WhatsApp. The README documents the capability map; API-to-service wiring beyond the sampled files is not fully shown, so uncertain links are omitted rather than inferred.

Main entry points: [`backend/app/services/notice_service.py`](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/notice_service.py) (Notice workflow), [`backend/app/services/document_service.py`](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/document_service.py) (Document handling), [`frontend/src/lib/api.ts`](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/frontend/src/lib/api.ts) (API client), [`backend/app/api`](https://github.com/eklakh-ai-engineer/taxtrace/tree/main/backend/app/api) (FastAPI routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reconcile["Reconciliation"]
  node_document_service["Document handling"]
  node_csv["CSV parser<br/>[csv_parser.py]"]
  node_json["JSON parser<br/>[json_parser.py]"]
  node_normalizer["Transaction normalization<br/>[normalizer.py]"]
  node_recon_service["Reconciliation workflow"]
  node_engine["Deterministic matching<br/>[engine.py]"]
  node_rules["Exception rules<br/>[rules.py]"]
end

subgraph group_respond["Notice and AI"]
  node_notice_api["Notice and draft routes<br/>[notices.py]"]
  node_notice_service["Notice workflow<br/>[notice_service.py]"]
  node_extractor["Notice extraction"]
  node_ai_service["AI assistance<br/>[ai_service.py]"]
  node_prompt["Prompt templates"]
  node_provider["AI provider<br/>[provider.py]"]
  node_retrieval["Evidence retrieval"]
  node_knowledge_ingest["Knowledge ingestion<br/>[ingest.py]"]
end

subgraph group_workflow["Firm workflows"]
  node_tasks["Task workflows<br/>[task_service.py]"]
  node_communications["Follow-up messages"]
  node_dashboard["Dashboard"]
  node_dashboard_api["Dashboard routes<br/>[dashboard.py]"]
  node_bot["Chat command router<br/>[bot_router.py]"]
  node_channel["Channel adapter<br/>[adapter.py]"]
end

subgraph group_platform["Platform services"]
  node_api["FastAPI routes"]
  node_auth["Authentication<br/>[auth.py]"]
  node_database[("Domain database<br/>[database.py]")]
  node_models["Domain records<br/>[models.py]"]
  node_audit["Audit trail<br/>[audit_service.py]"]
end

subgraph group_frontend["Review interface"]
  node_frontend_pages["Review pages"]
  node_frontend_api["API client<br/>[api.ts]"]
  node_exceptions_ui["Exception review<br/>[page.tsx]"]
  node_knowledge_ui["Knowledge interface<br/>[page.tsx]"]
  node_notice_ui["Notice review<br/>[page.tsx]"]
end

node_ca(("CA staff"))
node_browser(("Web user"))
node_whatsapp(("WhatsApp"))

node_ca -->|"uses"| node_browser
node_browser -->|"reviews"| node_frontend_pages
node_frontend_pages -.->|"requests"| node_frontend_api
node_frontend_api -.->|"calls API"| node_api
node_api -->|"authenticates"| node_auth
node_api -->|"uses sessions"| node_database
node_database -->|"stores records"| node_models
node_api -->|"delegates"| node_document_service
node_document_service -.->|"records events"| node_audit
node_document_service -.->|"parses CSV"| node_csv
node_document_service -.->|"parses JSON"| node_json
node_csv -->|"normalizes"| node_normalizer
node_recon_service -->|"runs matching"| node_engine
node_engine -->|"normalizes records"| node_normalizer
node_engine -->|"classifies"| node_rules
node_recon_service -->|"records outcome"| node_audit
node_exceptions_ui -.->|"requests review data"| node_frontend_api
node_notice_api -.->|"delegates"| node_notice_service
node_notice_service -->|"extracts notice"| node_extractor
node_notice_service -->|"retrieves evidence"| node_retrieval
node_notice_service -->|"uses documents"| node_document_service
node_notice_service -->|"generates drafts"| node_provider
node_ai_service -->|"formats prompts"| node_prompt
node_ai_service -->|"requests AI"| node_provider
node_retrieval -->|"embeds query"| node_provider
node_knowledge_ingest -->|"embeds content"| node_provider
node_knowledge_ui -.->|"requests knowledge"| node_frontend_api
node_notice_ui -.->|"requests drafts"| node_frontend_api
node_dashboard_api -->|"delegates"| node_dashboard
node_tasks -.->|"supports follow-up"| node_communications
node_whatsapp -->|"sends messages"| node_channel
node_channel -->|"routes messages"| node_bot
node_bot -->|"explains mismatch"| node_ai_service

click node_frontend_pages "https://github.com/eklakh-ai-engineer/taxtrace/tree/main/frontend/src/app"
click node_frontend_api "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/frontend/src/lib/api.ts"
click node_api "https://github.com/eklakh-ai-engineer/taxtrace/tree/main/backend/app/api"
click node_auth "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/auth.py"
click node_database "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/database.py"
click node_models "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/models.py"
click node_audit "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/audit_service.py"
click node_document_service "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/document_service.py"
click node_csv "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/parsers/csv_parser.py"
click node_json "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/parsers/json_parser.py"
click node_normalizer "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/parsers/normalizer.py"
click node_recon_service "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/reconciliation_service.py"
click node_engine "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/reconciliation/engine.py"
click node_rules "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/reconciliation/rules.py"
click node_exceptions_ui "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/frontend/src/app/exceptions/page.tsx"
click node_notice_api "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/api/notices.py"
click node_notice_service "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/notice_service.py"
click node_extractor "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/ai/notice_extractor.py"
click node_ai_service "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/ai_service.py"
click node_prompt "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/ai/prompt_templates.py"
click node_provider "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/ai/provider.py"
click node_retrieval "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/retrieval_service.py"
click node_knowledge_ingest "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/knowledge/ingest.py"
click node_knowledge_ui "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/frontend/src/app/knowledge/page.tsx"
click node_notice_ui "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/frontend/src/app/notices/%5Bid%5D/page.tsx"
click node_tasks "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/task_service.py"
click node_communications "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/communication_service.py"
click node_dashboard "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/dashboard_service.py"
click node_dashboard_api "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/api/dashboard.py"
click node_bot "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/channels/bot_router.py"
click node_channel "https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/channels/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_document_service,node_csv,node_json,node_normalizer,node_recon_service,node_engine,node_rules,node_browser toneBlue
class node_notice_api,node_notice_service,node_extractor,node_ai_service,node_prompt,node_provider,node_retrieval,node_knowledge_ingest toneAmber
class node_tasks,node_communications,node_dashboard,node_dashboard_api,node_bot,node_channel toneMint
class node_api,node_auth,node_database,node_models,node_audit toneRose
class node_frontend_pages,node_frontend_api,node_exceptions_ui,node_knowledge_ui,node_notice_ui,node_ca,node_whatsapp toneIndigo
```

## Components

### Reconciliation

- [Document handling](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/document_service.py): `backend/app/services/document_service.py`
- [CSV parser](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/parsers/csv_parser.py): `backend/app/parsers/csv_parser.py`
- [JSON parser](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/parsers/json_parser.py): `backend/app/parsers/json_parser.py`
- [Transaction normalization](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/parsers/normalizer.py): `backend/app/parsers/normalizer.py`
- [Reconciliation workflow](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/reconciliation_service.py): `backend/app/services/reconciliation_service.py`
- [Deterministic matching](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/reconciliation/engine.py): `backend/app/reconciliation/engine.py`
- [Exception rules](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/reconciliation/rules.py): `backend/app/reconciliation/rules.py`

### Notice and AI

- [Notice and draft routes](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/api/notices.py): `backend/app/api/notices.py`
- [Notice workflow](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/notice_service.py): `backend/app/services/notice_service.py`
- [Notice extraction](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/ai/notice_extractor.py): `backend/app/ai/notice_extractor.py`
- [AI assistance](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Prompt templates](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/ai/prompt_templates.py): `backend/app/ai/prompt_templates.py`
- [AI provider](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/ai/provider.py): `backend/app/ai/provider.py`
- [Evidence retrieval](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/retrieval_service.py): `backend/app/services/retrieval_service.py`
- [Knowledge ingestion](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/knowledge/ingest.py): `backend/app/knowledge/ingest.py`

### Firm workflows

- [Task workflows](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/task_service.py): `backend/app/services/task_service.py`
- [Follow-up messages](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/communication_service.py): `backend/app/services/communication_service.py`
- [Dashboard](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/dashboard_service.py): `backend/app/services/dashboard_service.py`
- [Dashboard routes](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/api/dashboard.py): `backend/app/api/dashboard.py`
- [Chat command router](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/channels/bot_router.py): `backend/app/channels/bot_router.py`
- [Channel adapter](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/channels/adapter.py): `backend/app/channels/adapter.py`

### Platform services

- [FastAPI routes](https://github.com/eklakh-ai-engineer/taxtrace/tree/main/backend/app/api): `backend/app/api`
- [Authentication](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Domain database](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/database.py): `backend/app/database.py`
- [Domain records](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/models.py): `backend/app/models.py`
- [Audit trail](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/backend/app/services/audit_service.py): `backend/app/services/audit_service.py`

### Review interface

- [Review pages](https://github.com/eklakh-ai-engineer/taxtrace/tree/main/frontend/src/app): `frontend/src/app`
- [API client](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Exception review](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/frontend/src/app/exceptions/page.tsx): `frontend/src/app/exceptions/page.tsx`
- [Knowledge interface](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/frontend/src/app/knowledge/page.tsx): `frontend/src/app/knowledge/page.tsx`
- [Notice review](https://github.com/eklakh-ai-engineer/taxtrace/blob/main/frontend/src/app/notices/%5Bid%5D/page.tsx): `frontend/src/app/notices/[id]/page.tsx`

### Other components

- **CA staff**
- **Web user**
- **WhatsApp**

## Connections

- CA staff → Web user: uses (evidence: `README.md`)
- Web user → Review pages: reviews (evidence: `README.md`)
- Review pages → API client: requests
- API client → FastAPI routes: calls API
- FastAPI routes → Authentication: authenticates (evidence: `backend/app/api/documents.py`)
- FastAPI routes → Domain database: uses sessions (evidence: `backend/app/api/documents.py`)
- Domain database → Domain records: stores records (evidence: `backend/app/models.py`)
- FastAPI routes → Document handling: delegates (evidence: `backend/app/api/documents.py`)
- Document handling → Audit trail: records events
- Document handling → CSV parser: parses CSV
- Document handling → JSON parser: parses JSON
- CSV parser → Transaction normalization: normalizes (evidence: `backend/app/parsers/csv_parser.py`)
- Reconciliation workflow → Deterministic matching: runs matching (evidence: `backend/app/services/reconciliation_service.py`)
- Deterministic matching → Transaction normalization: normalizes records (evidence: `backend/app/reconciliation/engine.py`)
- Deterministic matching → Exception rules: classifies (evidence: `backend/app/reconciliation/engine.py`)
- Reconciliation workflow → Audit trail: records outcome (evidence: `backend/app/services/reconciliation_service.py`)
- Exception review → API client: requests review data
- Notice and draft routes → Notice workflow: delegates
- Notice workflow → Notice extraction: extracts notice (evidence: `backend/app/services/notice_service.py`)
- Notice workflow → Evidence retrieval: retrieves evidence (evidence: `backend/app/services/notice_service.py`)
- Notice workflow → Document handling: uses documents (evidence: `backend/app/services/notice_service.py`)
- Notice workflow → AI provider: generates drafts (evidence: `backend/app/services/notice_service.py`)
- AI assistance → Prompt templates: formats prompts (evidence: `backend/app/services/ai_service.py`)
- AI assistance → AI provider: requests AI (evidence: `backend/app/services/ai_service.py`)
- Evidence retrieval → AI provider: embeds query (evidence: `backend/app/services/retrieval_service.py`)
- Knowledge ingestion → AI provider: embeds content (evidence: `backend/app/knowledge/ingest.py`)
- Knowledge interface → API client: requests knowledge
- Notice review → API client: requests drafts
- Dashboard routes → Dashboard: delegates (evidence: `backend/app/api/dashboard.py`)
- Task workflows → Follow-up messages: supports follow-up
- WhatsApp → Channel adapter: sends messages
- Channel adapter → Chat command router: routes messages (evidence: `backend/app/api/webhooks.py`)
- Chat command router → AI assistance: explains mismatch (evidence: `backend/app/channels/bot_router.py`)
