# zeus-pr/taxos architecture

> Architecture diagram of the GitHub repository zeus-pr/taxos, 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/zeus-pr/taxos
- Repository: https://github.com/zeus-pr/taxos

## Overview

TaxOS is a web application for organizing tax information and preparing an Indian income-tax return. The user workflow runs from account creation and tax-profile onboarding through document upload, income and deduction entry, reconciliation, tax calculation, eligibility/checklist review, and return review. The tree also shows investment projections, scenarios, reports, and administration features. Sampled routes confirm profile, income, deduction, authentication, and document storage behavior; the README provides no product detail, and processing, tax preparation, and several UI implementations were not sampled, so uncertain internal links are omitted.

Main entry points: [`lib/db/repo.ts`](https://github.com/zeus-pr/taxos/blob/main/lib/db/repo.ts) (Data repository), [`app/api/auth`](https://github.com/zeus-pr/taxos/tree/main/app/api/auth) (Authentication routes), [`app/api/documents`](https://github.com/zeus-pr/taxos/tree/main/app/api/documents) (Document routes), [`modules/tax-engine`](https://github.com/zeus-pr/taxos/tree/main/modules/tax-engine) (Tax calculation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and setup"]
  node_auth_ui["Sign-in screens"]
  node_auth_api["Authentication routes"]
  node_auth_service["Auth service<br/>[service.ts]"]
  node_session["Session handling<br/>[session.ts]"]
  node_profile_ui["Profile onboarding"]
  node_profile_api["Profile API<br/>[route.ts]"]
end

subgraph group_documents["Documents and data"]
  node_documents_ui["Document workspace"]
  node_document_api["Document routes"]
  node_document_service["Document processing<br/>[service.ts]"]
  node_parsers["Document parsers"]
  node_validation["Upload validation<br/>[validation.ts]"]
  node_storage["Private file storage<br/>[index.ts]"]
end

subgraph group_preparation["Tax preparation"]
  node_income_ui["Income and deductions"]
  node_income_api["Income routes"]
  node_income_service["Income service<br/>[service.ts]"]
  node_reconciliation["Data reconciliation<br/>[index.ts]"]
  node_tax_engine["Tax calculation"]
  node_itr_engine["Return eligibility"]
  node_review_ui["Return review"]
  node_reports["Tax reports"]
  node_investments["Investment projections<br/>[projection.ts]"]
end

subgraph group_operations["Administration"]
  node_admin_ui["Admin console"]
  node_repo["Data repository<br/>[repo.ts]"]
end

node_taxpayer(("Taxpayer"))
node_blob[("Vercel Blob")]
node_database[("Application database")]

node_taxpayer -->|"starts"| node_auth_ui
node_auth_ui -->|"submits credentials"| node_auth_api
node_auth_api -->|"authenticates"| node_auth_service
node_auth_api -->|"creates session"| node_session
node_auth_api -->|"reads users"| node_repo
node_auth_api -->|"sets session"| node_taxpayer
node_taxpayer -->|"enters profile"| node_profile_ui
node_profile_ui -->|"submits profile"| node_profile_api
node_profile_api -->|"reads and writes"| node_repo
node_taxpayer -->|"uploads documents"| node_documents_ui
node_documents_ui -->|"requests upload"| node_document_api
node_document_api -->|"validates file"| node_validation
node_document_api -->|"uploads and verifies"| node_blob
node_document_api -->|"records document"| node_repo
node_document_api -->|"downloads or deletes"| node_storage
node_storage -->|"accesses files"| node_blob
node_taxpayer -->|"enters tax data"| node_income_ui
node_income_ui -->|"submits entries"| node_income_api
node_income_api -->|"reads and writes"| node_repo
node_income_service -->|"accesses income data"| node_repo
node_document_service -->|"parses documents"| node_parsers
node_reconciliation -->|"supplies reconciled data"| node_tax_engine
node_tax_engine -->|"provides tax results"| node_itr_engine
node_taxpayer -->|"reviews return"| node_review_ui
node_review_ui -->|"uses eligibility"| node_itr_engine
node_reports -->|"summarizes tax"| node_tax_engine
node_taxpayer -->|"explores projections"| node_investments
node_admin_ui -->|"manages records"| node_repo
node_repo -->|"reads and writes"| node_database

click node_auth_ui "https://github.com/zeus-pr/taxos/tree/main/app/auth"
click node_auth_api "https://github.com/zeus-pr/taxos/tree/main/app/api/auth"
click node_auth_service "https://github.com/zeus-pr/taxos/blob/main/lib/auth/service.ts"
click node_session "https://github.com/zeus-pr/taxos/blob/main/lib/auth/session.ts"
click node_profile_ui "https://github.com/zeus-pr/taxos/tree/main/app/app/onboarding"
click node_profile_api "https://github.com/zeus-pr/taxos/blob/main/app/api/profile/route.ts"
click node_documents_ui "https://github.com/zeus-pr/taxos/tree/main/app/app/documents"
click node_document_api "https://github.com/zeus-pr/taxos/tree/main/app/api/documents"
click node_document_service "https://github.com/zeus-pr/taxos/blob/main/modules/documents/service.ts"
click node_parsers "https://github.com/zeus-pr/taxos/tree/main/modules/documents/parsers"
click node_validation "https://github.com/zeus-pr/taxos/blob/main/modules/documents/validation.ts"
click node_storage "https://github.com/zeus-pr/taxos/blob/main/lib/storage/index.ts"
click node_income_ui "https://github.com/zeus-pr/taxos/tree/main/app/app/income"
click node_income_api "https://github.com/zeus-pr/taxos/tree/main/app/api/income"
click node_income_service "https://github.com/zeus-pr/taxos/blob/main/modules/income/service.ts"
click node_reconciliation "https://github.com/zeus-pr/taxos/blob/main/modules/reconciliation/index.ts"
click node_tax_engine "https://github.com/zeus-pr/taxos/tree/main/modules/tax-engine"
click node_itr_engine "https://github.com/zeus-pr/taxos/tree/main/modules/itr-engine"
click node_review_ui "https://github.com/zeus-pr/taxos/tree/main/app/app/review"
click node_reports "https://github.com/zeus-pr/taxos/tree/main/modules/reports"
click node_investments "https://github.com/zeus-pr/taxos/blob/main/modules/investments/projection.ts"
click node_admin_ui "https://github.com/zeus-pr/taxos/tree/main/app/admin"
click node_repo "https://github.com/zeus-pr/taxos/blob/main/lib/db/repo.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_auth_ui,node_auth_api,node_auth_service,node_session,node_profile_ui,node_profile_api toneBlue
class node_documents_ui,node_document_api,node_document_service,node_parsers,node_validation,node_storage,node_blob,node_database toneAmber
class node_income_ui,node_income_api,node_income_service,node_reconciliation,node_tax_engine,node_itr_engine,node_review_ui,node_reports,node_investments toneMint
class node_admin_ui,node_repo toneRose
class node_taxpayer toneIndigo
```

## Components

### Access and setup

- [Sign-in screens](https://github.com/zeus-pr/taxos/tree/main/app/auth): `app/auth`
- [Authentication routes](https://github.com/zeus-pr/taxos/tree/main/app/api/auth): `app/api/auth`
- [Auth service](https://github.com/zeus-pr/taxos/blob/main/lib/auth/service.ts): `lib/auth/service.ts`
- [Session handling](https://github.com/zeus-pr/taxos/blob/main/lib/auth/session.ts): `lib/auth/session.ts`
- [Profile onboarding](https://github.com/zeus-pr/taxos/tree/main/app/app/onboarding): `app/app/onboarding`
- [Profile API](https://github.com/zeus-pr/taxos/blob/main/app/api/profile/route.ts): `app/api/profile/route.ts`

### Documents and data

- [Document workspace](https://github.com/zeus-pr/taxos/tree/main/app/app/documents): `app/app/documents`
- [Document routes](https://github.com/zeus-pr/taxos/tree/main/app/api/documents): `app/api/documents`
- [Document processing](https://github.com/zeus-pr/taxos/blob/main/modules/documents/service.ts): `modules/documents/service.ts`
- [Document parsers](https://github.com/zeus-pr/taxos/tree/main/modules/documents/parsers): `modules/documents/parsers`
- [Upload validation](https://github.com/zeus-pr/taxos/blob/main/modules/documents/validation.ts): `modules/documents/validation.ts`
- [Private file storage](https://github.com/zeus-pr/taxos/blob/main/lib/storage/index.ts): `lib/storage/index.ts`

### Tax preparation

- [Income and deductions](https://github.com/zeus-pr/taxos/tree/main/app/app/income): `app/app/income`
- [Income routes](https://github.com/zeus-pr/taxos/tree/main/app/api/income): `app/api/income`
- [Income service](https://github.com/zeus-pr/taxos/blob/main/modules/income/service.ts): `modules/income/service.ts`
- [Data reconciliation](https://github.com/zeus-pr/taxos/blob/main/modules/reconciliation/index.ts): `modules/reconciliation/index.ts`
- [Tax calculation](https://github.com/zeus-pr/taxos/tree/main/modules/tax-engine): `modules/tax-engine`
- [Return eligibility](https://github.com/zeus-pr/taxos/tree/main/modules/itr-engine): `modules/itr-engine`
- [Return review](https://github.com/zeus-pr/taxos/tree/main/app/app/review): `app/app/review`
- [Tax reports](https://github.com/zeus-pr/taxos/tree/main/modules/reports): `modules/reports`
- [Investment projections](https://github.com/zeus-pr/taxos/blob/main/modules/investments/projection.ts): `modules/investments/projection.ts`

### Administration

- [Admin console](https://github.com/zeus-pr/taxos/tree/main/app/admin): `app/admin`
- [Data repository](https://github.com/zeus-pr/taxos/blob/main/lib/db/repo.ts): `lib/db/repo.ts`

### Other components

- **Taxpayer**
- **Vercel Blob**
- **Application database**

## Connections

- Taxpayer → Sign-in screens: starts
- Sign-in screens → Authentication routes: submits credentials
- Authentication routes → Auth service: authenticates
- Authentication routes → Session handling: creates session
- Authentication routes → Data repository: reads users
- Authentication routes → Taxpayer: sets session
- Taxpayer → Profile onboarding: enters profile
- Profile onboarding → Profile API: submits profile
- Profile API → Data repository: reads and writes
- Taxpayer → Document workspace: uploads documents
- Document workspace → Document routes: requests upload
- Document routes → Upload validation: validates file
- Document routes → Vercel Blob: uploads and verifies
- Document routes → Data repository: records document
- Document routes → Private file storage: downloads or deletes
- Private file storage → Vercel Blob: accesses files
- Taxpayer → Income and deductions: enters tax data
- Income and deductions → Income routes: submits entries
- Income routes → Data repository: reads and writes
- Income service → Data repository: accesses income data
- Document processing → Document parsers: parses documents
- Data reconciliation → Tax calculation: supplies reconciled data
- Tax calculation → Return eligibility: provides tax results
- Taxpayer → Return review: reviews return
- Return review → Return eligibility: uses eligibility
- Tax reports → Tax calculation: summarizes tax
- Taxpayer → Investment projections: explores projections
- Admin console → Data repository: manages records
- Data repository → Application database: reads and writes