# mjsharma1234/ca-agentic-platform architecture

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

- Interactive diagram: https://gitdiagram.com/mjsharma1234/ca-agentic-platform
- Repository: https://github.com/mjsharma1234/ca-agentic-platform

## Overview

CA Firm OS is a multi-tenant operations tracker and compliance-preparation platform for Indian CA firms; professionals, not automation, make filing decisions. The workflow runs from client and document intake through reconciliation and return preparation to human review and partner approval, while tracking filing status rather than filing returns. The graph also preserves the documented statutory calendar, billing, Tally exchange, audit, and agent capabilities. Relationships for unsampled modules are included only where documented in the README; source excerpts do not establish every internal call.

Main entry points: [`backend/app/main.py`](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/main.py) (API Application), [`backend/app/api/v1/firm_os.py`](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/firm_os.py) (Firm State API), [`backend/app/api/v1/auth.py`](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/auth.py) (Authentication), [`backend/app/api/v1/returns.py`](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/returns.py) (Return Preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface and API"]
  node_web["Firm OS Web"]
  node_app["API Application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_workflow["Firm Operations"]
  node_clients["Client Intake<br/>[clients.py]"]
  node_documents["Document Intake<br/>[documents.py]"]
  node_ops["Ops Tracker<br/>[ops.py]"]
  node_calendar["Statutory Calendar"]
  node_billing["Billing and Recovery<br/>[billing.py]"]
  node_returns["Return Preparation<br/>[returns.py]"]
  node_firmstate["Firm State API<br/>[firm_os.py]"]
end

subgraph group_automation["Preparation Engines"]
  node_agent["Agent Runtime<br/>[runtime.py]"]
  node_ocr["OCR Engine<br/>[ocr_engine.py]"]
  node_reconcile["Reconciliation<br/>[reconciler.py]"]
  node_bank["Bank Reconciliation<br/>[bank_reconciler.py]"]
  node_tally["Tally Exchange<br/>[tally_bridge.py]"]
end

subgraph group_governance["State and Governance"]
  node_gates["Human Review Gates<br/>[gates.py]"]
  node_audit["Audit Chain<br/>[audit_chain.py]"]
  node_database[("Relational Database<br/>[database.py]")]
  node_tenant["Tenant and User Records<br/>[tenant.py]"]
end

node_staff(("Firm Staff"))

node_staff -->|"uses"| node_web
node_web -.->|"requests APIs"| node_app
node_app -->|"mounts routes"| node_auth
node_app -->|"mounts routes"| node_clients
node_app -->|"mounts routes"| node_documents
node_app -->|"mounts routes"| node_ops
node_app -->|"mounts routes"| node_billing
node_app -->|"mounts routes"| node_returns
node_app -->|"mounts routes"| node_gates
node_app -->|"mounts routes"| node_firmstate
node_documents -->|"extracts documents"| node_ocr
node_returns -->|"runs reconciliation"| node_reconcile
node_firmstate -->|"runs reconciliation"| node_reconcile
node_firmstate -->|"exports XML"| node_tally
node_bank -.->|"exchanges data"| node_tally
node_ops -->|"tracks deadlines"| node_calendar
node_gates -.->|"records decisions"| node_audit
node_firmstate -->|"serves audit trail"| node_audit
node_clients -->|"reads and writes"| node_database
node_billing -->|"reads and writes"| node_database
node_auth -->|"looks up users"| node_tenant
node_auth -->|"appends login event"| node_audit
node_agent -.->|"prepares returns"| node_returns

click node_web "https://github.com/mjsharma1234/ca-agentic-platform/tree/master/firm_os_web"
click node_app "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/main.py"
click node_auth "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/auth.py"
click node_clients "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/clients.py"
click node_documents "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/documents.py"
click node_ops "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/ops.py"
click node_calendar "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/deterministic_core/statutory_calendar_live.py"
click node_billing "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/billing.py"
click node_returns "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/returns.py"
click node_gates "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/gates.py"
click node_agent "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/agents/runtime.py"
click node_ocr "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/deterministic_core/ocr_engine.py"
click node_reconcile "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/deterministic_core/reconciler.py"
click node_bank "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/deterministic_core/bank_reconciler.py"
click node_tally "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/deterministic_core/tally_bridge.py"
click node_audit "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/deterministic_core/audit_chain.py"
click node_firmstate "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/firm_os.py"
click node_database "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/core/database.py"
click node_tenant "https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/models/tenant.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,node_app,node_auth toneBlue
class node_clients,node_documents,node_ops,node_calendar,node_billing,node_returns,node_firmstate toneAmber
class node_agent,node_ocr,node_reconcile,node_bank,node_tally toneMint
class node_gates,node_audit,node_database,node_tenant toneRose
class node_staff toneIndigo
```

## Components

### User Interface and API

- [Firm OS Web](https://github.com/mjsharma1234/ca-agentic-platform/tree/master/firm_os_web): `firm_os_web`
- [API Application](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`

### Firm Operations

- [Client Intake](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/clients.py): `backend/app/api/v1/clients.py`
- [Document Intake](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/documents.py): `backend/app/api/v1/documents.py`
- [Ops Tracker](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/ops.py): `backend/app/api/v1/ops.py`
- [Statutory Calendar](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/deterministic_core/statutory_calendar_live.py): `backend/app/deterministic_core/statutory_calendar_live.py`
- [Billing and Recovery](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/billing.py): `backend/app/api/v1/billing.py`
- [Return Preparation](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/returns.py): `backend/app/api/v1/returns.py`
- [Firm State API](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/firm_os.py): `backend/app/api/v1/firm_os.py`

### Preparation Engines

- [Agent Runtime](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/agents/runtime.py): `backend/app/agents/runtime.py`
- [OCR Engine](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/deterministic_core/ocr_engine.py): `backend/app/deterministic_core/ocr_engine.py`
- [Reconciliation](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/deterministic_core/reconciler.py): `backend/app/deterministic_core/reconciler.py`
- [Bank Reconciliation](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/deterministic_core/bank_reconciler.py): `backend/app/deterministic_core/bank_reconciler.py`
- [Tally Exchange](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/deterministic_core/tally_bridge.py): `backend/app/deterministic_core/tally_bridge.py`

### State and Governance

- [Human Review Gates](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/api/v1/gates.py): `backend/app/api/v1/gates.py`
- [Audit Chain](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/deterministic_core/audit_chain.py): `backend/app/deterministic_core/audit_chain.py`
- [Relational Database](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/core/database.py): `backend/app/core/database.py`
- [Tenant and User Records](https://github.com/mjsharma1234/ca-agentic-platform/blob/master/backend/app/models/tenant.py): `backend/app/models/tenant.py`

### Other components

- **Firm Staff**

## Connections

- Firm Staff → Firm OS Web: uses
- Firm OS Web → API Application: requests APIs
- API Application → Authentication: mounts routes (evidence: `backend/app/main.py`)
- API Application → Client Intake: mounts routes (evidence: `backend/app/main.py`)
- API Application → Document Intake: mounts routes (evidence: `backend/app/main.py`)
- API Application → Ops Tracker: mounts routes (evidence: `backend/app/main.py`)
- API Application → Billing and Recovery: mounts routes (evidence: `backend/app/main.py`)
- API Application → Return Preparation: mounts routes (evidence: `backend/app/main.py`)
- API Application → Human Review Gates: mounts routes (evidence: `backend/app/main.py`)
- API Application → Firm State API: mounts routes (evidence: `backend/app/main.py`)
- Document Intake → OCR Engine: extracts documents (evidence: `backend/app/api/v1/documents.py`)
- Return Preparation → Reconciliation: runs reconciliation (evidence: `backend/app/api/v1/returns.py`)
- Firm State API → Reconciliation: runs reconciliation (evidence: `backend/app/api/v1/firm_os.py`)
- Firm State API → Tally Exchange: exports XML (evidence: `backend/app/api/v1/firm_os.py`)
- Bank Reconciliation → Tally Exchange: exchanges data
- Ops Tracker → Statutory Calendar: tracks deadlines
- Human Review Gates → Audit Chain: records decisions (evidence: `backend/app/api/v1/gates.py`)
- Firm State API → Audit Chain: serves audit trail (evidence: `backend/app/api/v1/firm_os.py`)
- Client Intake → Relational Database: reads and writes (evidence: `backend/app/api/v1/clients.py`)
- Billing and Recovery → Relational Database: reads and writes (evidence: `backend/app/api/v1/billing.py`)
- Authentication → Tenant and User Records: looks up users (evidence: `backend/app/api/v1/auth.py`)
- Authentication → Audit Chain: appends login event (evidence: `backend/app/api/v1/auth.py`)
- Agent Runtime → Return Preparation: prepares returns
