# basit-94/incometax architecture

> Architecture diagram of the GitHub repository basit-94/incometax, 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/basit-94/incometax
- Repository: https://github.com/basit-94/incometax

## Overview

Wapsi is a synthetic Indian income-tax filing prototype: citizens gather and confirm facts, compare tax regimes, and prepare a return through manual or agentic journeys. The Next.js app also exposes document, vault, DigiLocker-mock, and chartered-accountant review capabilities. An additive Spring Boot boundary demonstrates authentication, tax computation, filing submissions, and history; submissions are local engineering records, not filings with an official department. The README and sampled routes establish the major boundaries; unsampled feature wiring is shown only where documented.

Main entry points: [`backend/src/main/java/com/wapsi/backend/submission/SubmissionService.java`](https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/submission/SubmissionService.java) (Submission service), [`app/page.tsx`](https://github.com/basit-94/incometax/blob/main/app/page.tsx) (Manual journey), [`app/api/extract/route.ts`](https://github.com/basit-94/incometax/blob/main/app/api/extract/route.ts) (Document extraction API), [`app/api/agent/route.ts`](https://github.com/basit-94/incometax/blob/main/app/api/agent/route.ts) (Copilot API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_citizen["Citizen journeys"]
  node_manual_ui["Manual journey<br/>[page.tsx]"]
  node_agent_ui["Agentic workspace<br/>[workspace.tsx]"]
  node_agent_runs["Run API<br/>[route.ts]"]
  node_agent_runtime["Run runtime<br/>[runtime.ts]"]
end

subgraph group_intake["Documents and assistance"]
  node_extract_api["Document extraction API<br/>[route.ts]"]
  node_pdf_extract["PDF extraction<br/>[pdfExtract.ts]"]
  node_vault_api["Vault API<br/>[route.ts]"]
  node_vault_service["Vault service<br/>[service.ts]"]
  node_locker_api["DigiLocker mock API<br/>[route.ts]"]
  node_agent_api["Copilot API<br/>[route.ts]"]
  node_copilot["Copilot tools<br/>[copilot-engine.ts]"]
end

subgraph group_return["Return intelligence"]
  node_return_state["Return state and commands<br/>[state.ts]"]
  node_tax_adapter["AY 2026-27 adapter<br/>[taxEngineAY2026.ts]"]
  node_ts_engine["Tax engine<br/>[tax.ts]"]
end

subgraph group_backend["Backend boundary"]
  node_backend_auth["Backend authentication"]
  node_backend_submission["Submission API"]
  node_submission_service["Submission service"]
  node_java_engine["Java tax engine<br/>[TaxEngine.java]"]
  node_rules["Versioned tax rules<br/>[RuleSetLoader.java]"]
end

subgraph group_state["State and integrations"]
  node_ledger[("Fact ledger<br/>[FactLedger.java]")]
  node_submission_store[("Submission store")]
  node_carry_forward["Carry-forward history"]
  node_postgres[("PostgreSQL<br/>[postgres.ts]")]
end

node_citizen_actor(("Citizen"))
node_gemini["Gemini model"]

node_citizen_actor -->|"uses"| node_manual_ui
node_citizen_actor -->|"uses"| node_agent_ui
node_agent_ui -->|"starts runs"| node_agent_runs
node_agent_runs -->|"creates and advances"| node_agent_runtime
node_citizen_actor -->|"uploads documents"| node_extract_api
node_extract_api -->|"extracts fields"| node_pdf_extract
node_extract_api -.->|"interprets ambiguity"| node_gemini
node_citizen_actor -->|"manages documents"| node_vault_api
node_vault_api -->|"reads and writes"| node_postgres
node_citizen_actor -->|"requests document pull"| node_locker_api
node_locker_api -->|"imports issued documents"| node_vault_service
node_citizen_actor -->|"chats"| node_agent_api
node_agent_api -->|"executes tools"| node_copilot
node_agent_api -.->|"requests model response"| node_gemini
node_copilot -->|"computes tax"| node_ts_engine
node_tax_adapter -->|"computes regimes"| node_ts_engine
node_manual_ui -->|"signs in"| node_backend_auth
node_manual_ui -->|"submits return"| node_backend_submission
node_submission_service -->|"loads rule set"| node_rules
node_submission_service -->|"computes submission"| node_java_engine
node_submission_service -->|"deduplicates and records"| node_submission_store
node_submission_service -->|"appends facts"| node_ledger
node_carry_forward -->|"finds completed return"| node_submission_store
node_carry_forward -->|"reads projection"| node_ledger

click node_manual_ui "https://github.com/basit-94/incometax/blob/main/app/page.tsx"
click node_agent_ui "https://github.com/basit-94/incometax/blob/main/components/agentic/workspace.tsx"
click node_agent_runs "https://github.com/basit-94/incometax/blob/main/app/api/runs/route.ts"
click node_agent_runtime "https://github.com/basit-94/incometax/blob/main/lib/agentic/runtime.ts"
click node_extract_api "https://github.com/basit-94/incometax/blob/main/app/api/extract/route.ts"
click node_pdf_extract "https://github.com/basit-94/incometax/blob/main/lib/compliance/pdfExtract.ts"
click node_vault_api "https://github.com/basit-94/incometax/blob/main/app/api/vault/route.ts"
click node_vault_service "https://github.com/basit-94/incometax/blob/main/lib/vault/service.ts"
click node_locker_api "https://github.com/basit-94/incometax/blob/main/app/api/digilocker/route.ts"
click node_agent_api "https://github.com/basit-94/incometax/blob/main/app/api/agent/route.ts"
click node_copilot "https://github.com/basit-94/incometax/blob/main/lib/agent/copilot-engine.ts"
click node_return_state "https://github.com/basit-94/incometax/blob/main/lib/return/state.ts"
click node_tax_adapter "https://github.com/basit-94/incometax/blob/main/lib/taxEngineAY2026.ts"
click node_ts_engine "https://github.com/basit-94/incometax/blob/main/lib/engine/tax.ts"
click node_backend_auth "https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/auth/AuthController.java"
click node_backend_submission "https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/submission/SubmissionController.java"
click node_submission_service "https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/submission/SubmissionService.java"
click node_java_engine "https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/engine/TaxEngine.java"
click node_rules "https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/rules/RuleSetLoader.java"
click node_ledger "https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/ledger/FactLedger.java"
click node_submission_store "https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/submission/SubmissionStore.java"
click node_carry_forward "https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/history/CarryForwardService.java"
click node_postgres "https://github.com/basit-94/incometax/blob/main/lib/db/postgres.ts"

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_manual_ui,node_agent_ui,node_agent_runs,node_agent_runtime toneBlue
class node_extract_api,node_pdf_extract,node_vault_api,node_vault_service,node_locker_api,node_agent_api,node_copilot toneAmber
class node_return_state,node_tax_adapter,node_ts_engine toneMint
class node_backend_auth,node_backend_submission,node_submission_service,node_java_engine,node_rules toneRose
class node_ledger,node_submission_store,node_carry_forward,node_postgres,node_citizen_actor,node_gemini toneIndigo
```

## Components

### Citizen journeys

- [Manual journey](https://github.com/basit-94/incometax/blob/main/app/page.tsx): `app/page.tsx`
- [Agentic workspace](https://github.com/basit-94/incometax/blob/main/components/agentic/workspace.tsx): `components/agentic/workspace.tsx`
- [Run API](https://github.com/basit-94/incometax/blob/main/app/api/runs/route.ts): `app/api/runs/route.ts`
- [Run runtime](https://github.com/basit-94/incometax/blob/main/lib/agentic/runtime.ts): `lib/agentic/runtime.ts`

### Documents and assistance

- [Document extraction API](https://github.com/basit-94/incometax/blob/main/app/api/extract/route.ts): `app/api/extract/route.ts`
- [PDF extraction](https://github.com/basit-94/incometax/blob/main/lib/compliance/pdfExtract.ts): `lib/compliance/pdfExtract.ts`
- [Vault API](https://github.com/basit-94/incometax/blob/main/app/api/vault/route.ts): `app/api/vault/route.ts`
- [Vault service](https://github.com/basit-94/incometax/blob/main/lib/vault/service.ts): `lib/vault/service.ts`
- [DigiLocker mock API](https://github.com/basit-94/incometax/blob/main/app/api/digilocker/route.ts): `app/api/digilocker/route.ts`
- [Copilot API](https://github.com/basit-94/incometax/blob/main/app/api/agent/route.ts): `app/api/agent/route.ts`
- [Copilot tools](https://github.com/basit-94/incometax/blob/main/lib/agent/copilot-engine.ts): `lib/agent/copilot-engine.ts`

### Return intelligence

- [Return state and commands](https://github.com/basit-94/incometax/blob/main/lib/return/state.ts): `lib/return/state.ts`
- [AY 2026-27 adapter](https://github.com/basit-94/incometax/blob/main/lib/taxEngineAY2026.ts): `lib/taxEngineAY2026.ts`
- [Tax engine](https://github.com/basit-94/incometax/blob/main/lib/engine/tax.ts): `lib/engine/tax.ts`

### Backend boundary

- [Backend authentication](https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/auth/AuthController.java): `backend/src/main/java/com/wapsi/backend/auth/AuthController.java`
- [Submission API](https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/submission/SubmissionController.java): `backend/src/main/java/com/wapsi/backend/submission/SubmissionController.java`
- [Submission service](https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/submission/SubmissionService.java): `backend/src/main/java/com/wapsi/backend/submission/SubmissionService.java`
- [Java tax engine](https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/engine/TaxEngine.java): `backend/src/main/java/com/wapsi/backend/engine/TaxEngine.java`
- [Versioned tax rules](https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/rules/RuleSetLoader.java): `backend/src/main/java/com/wapsi/backend/rules/RuleSetLoader.java`

### State and integrations

- [Fact ledger](https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/ledger/FactLedger.java): `backend/src/main/java/com/wapsi/backend/ledger/FactLedger.java`
- [Submission store](https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/submission/SubmissionStore.java): `backend/src/main/java/com/wapsi/backend/submission/SubmissionStore.java`
- [Carry-forward history](https://github.com/basit-94/incometax/blob/main/backend/src/main/java/com/wapsi/backend/history/CarryForwardService.java): `backend/src/main/java/com/wapsi/backend/history/CarryForwardService.java`
- [PostgreSQL](https://github.com/basit-94/incometax/blob/main/lib/db/postgres.ts): `lib/db/postgres.ts`

### Other components

- **Citizen**
- **Gemini model**

## Connections

- Citizen → Manual journey: uses
- Citizen → Agentic workspace: uses
- Agentic workspace → Run API: starts runs
- Run API → Run runtime: creates and advances
- Citizen → Document extraction API: uploads documents
- Document extraction API → PDF extraction: extracts fields
- Document extraction API → Gemini model: interprets ambiguity
- Citizen → Vault API: manages documents
- Vault API → PostgreSQL: reads and writes
- Citizen → DigiLocker mock API: requests document pull
- DigiLocker mock API → Vault service: imports issued documents
- Citizen → Copilot API: chats
- Copilot API → Copilot tools: executes tools
- Copilot API → Gemini model: requests model response
- Copilot tools → Tax engine: computes tax
- AY 2026-27 adapter → Tax engine: computes regimes
- Manual journey → Backend authentication: signs in
- Manual journey → Submission API: submits return
- Submission service → Versioned tax rules: loads rule set
- Submission service → Java tax engine: computes submission
- Submission service → Submission store: deduplicates and records
- Submission service → Fact ledger: appends facts
- Carry-forward history → Submission store: finds completed return
- Carry-forward history → Fact ledger: reads projection