# shreeganeshkanoujiya/kosh architecture

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

## Overview

Kosh is a multi-company petty-cash application. Staff sign in, record expenses manually or from UPI screenshots and receipts, then submit them for review; approval updates cash balances and feeds dashboards and reports. The README documents the route → service → repository structure and the approval states. The graph preserves those stages and major capabilities; several UI/API and unsampled subsystem links are shown as unverified where the supplied excerpts do not establish their runtime wiring.

Main entry points: [`src/app/api`](https://github.com/shreeganeshkanoujiya/kosh/tree/main/src/app/api) (API routes), [`src/repositories`](https://github.com/shreeganeshkanoujiya/kosh/tree/main/src/repositories) (Data repositories), [`src/services/transaction.service.ts`](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/transaction.service.ts) (Expense rules), [`src/services/auth.service.ts`](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/auth.service.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["App pages"]
  node_expense_ui["Expense entry<br/>[entry-form.tsx]"]
  node_approval_ui["Approval view<br/>[approvals-view.tsx]"]
end

subgraph group_workflow["Expense workflow"]
  node_transaction["Expense rules"]
  node_policy["Approval policy<br/>[entry-policy.ts]"]
  node_ocr["UPI extraction<br/>[ocr.service.ts]"]
  node_attachments["Receipt handling"]
end

subgraph group_business["Business capabilities"]
  node_dashboard["Cash dashboard"]
  node_reports["Reports and export<br/>[report.service.ts]"]
  node_admin["Company administration<br/>[role.service.ts]"]
  node_audit["Audit trail<br/>[audit.service.ts]"]
end

subgraph group_platform["Request and identity"]
  node_api["API routes"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_session["Session validation<br/>[session.service.ts]"]
  node_mailer["SMTP mail"]
end

subgraph group_data["Persistence"]
  node_storage["File storage"]
  node_repositories["Data repositories"]
  node_database[("PostgreSQL<br/>[prisma.ts]")]
end

node_staff(("Company staff"))

node_staff -->|"uses"| node_web
node_web -.->|"records expenses"| node_expense_ui
node_expense_ui -.->|"submits entries"| node_api
node_approval_ui -.->|"reviews entries"| node_api
node_api -->|"dispatches"| node_transaction
node_api -->|"dispatches"| node_auth
node_api -->|"dispatches"| node_reports
node_api -->|"dispatches"| node_admin
node_transaction -->|"enforces states"| node_policy
node_transaction -->|"reads and writes"| node_repositories
node_reports -->|"reads data"| node_repositories
node_repositories -->|"queries"| node_database
node_api -.->|"dispatches"| node_ocr
node_ocr -.->|"uses screenshot"| node_attachments
node_api -->|"dispatches"| node_attachments
node_attachments -.->|"stores files"| node_storage
node_api -.->|"dispatches"| node_dashboard
node_api -.->|"dispatches"| node_audit
node_api -->|"checks identity"| node_session
node_auth -->|"starts sessions"| node_session
node_session -->|"persists sessions"| node_repositories
node_auth -->|"sends reset mail"| node_mailer
node_admin -->|"reads and writes"| node_repositories
node_audit -->|"writes events"| node_repositories

click node_web "https://github.com/shreeganeshkanoujiya/kosh/tree/main/src/app/(app)"
click node_expense_ui "https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/components/transactions/entry-form.tsx"
click node_approval_ui "https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/components/approvals/approvals-view.tsx"
click node_api "https://github.com/shreeganeshkanoujiya/kosh/tree/main/src/app/api"
click node_auth "https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/auth.service.ts"
click node_session "https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/session.service.ts"
click node_transaction "https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/transaction.service.ts"
click node_policy "https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/entry-policy.ts"
click node_ocr "https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/ocr.service.ts"
click node_attachments "https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/attachment.service.ts"
click node_storage "https://github.com/shreeganeshkanoujiya/kosh/tree/main/src/lib/storage"
click node_dashboard "https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/dashboard.service.ts"
click node_reports "https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/report.service.ts"
click node_admin "https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/role.service.ts"
click node_audit "https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/audit.service.ts"
click node_repositories "https://github.com/shreeganeshkanoujiya/kosh/tree/main/src/repositories"
click node_database "https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/lib/db/prisma.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_web,node_expense_ui,node_approval_ui toneBlue
class node_transaction,node_policy,node_ocr,node_attachments toneAmber
class node_dashboard,node_reports,node_admin,node_audit toneMint
class node_api,node_auth,node_session,node_mailer toneRose
class node_storage,node_repositories,node_database,node_staff toneIndigo
```

## Components

### User experience

- [App pages](https://github.com/shreeganeshkanoujiya/kosh/tree/main/src/app/(app)): `src/app/(app)`
- [Expense entry](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/components/transactions/entry-form.tsx): `src/components/transactions/entry-form.tsx`
- [Approval view](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/components/approvals/approvals-view.tsx): `src/components/approvals/approvals-view.tsx`

### Expense workflow

- [Expense rules](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/transaction.service.ts): `src/services/transaction.service.ts`
- [Approval policy](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/entry-policy.ts): `src/services/entry-policy.ts`
- [UPI extraction](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/ocr.service.ts): `src/services/ocr.service.ts`
- [Receipt handling](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/attachment.service.ts): `src/services/attachment.service.ts`

### Business capabilities

- [Cash dashboard](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/dashboard.service.ts): `src/services/dashboard.service.ts`
- [Reports and export](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/report.service.ts): `src/services/report.service.ts`
- [Company administration](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/role.service.ts): `src/services/role.service.ts`
- [Audit trail](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/audit.service.ts): `src/services/audit.service.ts`

### Request and identity

- [API routes](https://github.com/shreeganeshkanoujiya/kosh/tree/main/src/app/api): `src/app/api`
- [Authentication](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/auth.service.ts): `src/services/auth.service.ts`
- [Session validation](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/services/session.service.ts): `src/services/session.service.ts`
- **SMTP mail**

### Persistence

- [File storage](https://github.com/shreeganeshkanoujiya/kosh/tree/main/src/lib/storage): `src/lib/storage`
- [Data repositories](https://github.com/shreeganeshkanoujiya/kosh/tree/main/src/repositories): `src/repositories`
- [PostgreSQL](https://github.com/shreeganeshkanoujiya/kosh/blob/main/src/lib/db/prisma.ts): `src/lib/db/prisma.ts`

### Other components

- **Company staff**

## Connections

- Company staff → App pages: uses (evidence: `README.md`)
- App pages → Expense entry: records expenses
- Expense entry → API routes: submits entries
- Approval view → API routes: reviews entries
- API routes → Expense rules: dispatches (evidence: `src/app/api/transactions/route.ts`)
- API routes → Authentication: dispatches (evidence: `src/app/api/me/route.ts`)
- API routes → Reports and export: dispatches (evidence: `src/app/api/reports/route.ts`)
- API routes → Company administration: dispatches (evidence: `src/app/api/roles/route.ts`)
- Expense rules → Approval policy: enforces states (evidence: `README.md`)
- Expense rules → Data repositories: reads and writes (evidence: `README.md`)
- Reports and export → Data repositories: reads data (evidence: `README.md`)
- Data repositories → PostgreSQL: queries (evidence: `src/repositories/entry.repository.ts`)
- API routes → UPI extraction: dispatches
- UPI extraction → Receipt handling: uses screenshot
- API routes → Receipt handling: dispatches (evidence: `src/app/api/attachments/route.ts`)
- Receipt handling → File storage: stores files
- API routes → Cash dashboard: dispatches
- API routes → Audit trail: dispatches
- API routes → Session validation: checks identity
- Authentication → Session validation: starts sessions (evidence: `src/services/auth.service.ts`)
- Session validation → Data repositories: persists sessions (evidence: `src/services/session.service.ts`)
- Authentication → SMTP mail: sends reset mail (evidence: `src/services/auth.service.ts`)
- Company administration → Data repositories: reads and writes (evidence: `README.md`)
- Audit trail → Data repositories: writes events (evidence: `src/services/audit.service.ts`)
