# cloudmonks-1000/invoice architecture

> Architecture diagram of the GitHub repository cloudmonks-1000/invoice, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudmonks-1000/invoice
- Repository: https://github.com/cloudmonks-1000/invoice

## Overview

Invoice Automation is a web application for users to retrieve invoice vouchers and review processing results, with administrative views for users and system activity. The main workflow is a user submitting a voucher request, which is authenticated, recorded, resolved against Oracle-backed voucher data, and returned as a PDF or ZIP. The tree also exposes bulk upload, history/export, dashboard, and administration capabilities. Several UI-to-API connections and the bulk-processing internals are not shown in the sampled source, so those details are not inferred.

Main entry points: [`src/db/oracle.ts`](https://github.com/cloudmonks-1000/invoice/blob/main/src/db/oracle.ts) (Oracle connection), [`src/App.tsx`](https://github.com/cloudmonks-1000/invoice/blob/main/src/App.tsx) (Main app), [`src/auth/auth.ts`](https://github.com/cloudmonks-1000/invoice/blob/main/src/auth/auth.ts) (Auth helper), [`app/api/invoices/[voucherNumber]/route.ts`](https://github.com/cloudmonks-1000/invoice/blob/main/app/api/invoices/%5BvoucherNumber%5D/route.ts) (Voucher download)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_main_app["Main app<br/>[App.tsx]"]
  node_dashboard_ui["Dashboard UI<br/>[Dashboard.tsx]"]
  node_history_ui["History UI<br/>[History.tsx]"]
  node_summary_ui["Summary UI<br/>[Summary.tsx]"]
  node_admin_ui["Admin pages"]
end

subgraph group_workflow["Invoice workflows"]
  node_dashboard_api["Dashboard API<br/>[route.ts]"]
  node_history_api["History API<br/>[route.ts]"]
  node_export_api["History export<br/>[route.ts]"]
  node_voucher_api["Voucher download<br/>[route.ts]"]
  node_bulk_api["Bulk upload<br/>[route.ts]"]
  node_download_service["Download service"]
  node_zip_util["ZIP creation<br/>[zip.ts]"]
end

subgraph group_identity["Identity and admin"]
  node_login_api["Login API<br/>[route.ts]"]
  node_refresh_api["Session refresh<br/>[route.ts]"]
  node_auth_api["Auth routes"]
  node_auth["Auth helper<br/>[auth.ts]"]
  node_rate_limit["Login rate limit"]
  node_admin_api["Admin APIs"]
end

subgraph group_storage["Oracle persistence"]
  node_records_repo["Records repository"]
  node_voucher_repo["Voucher repository"]
  node_auth_repo["Auth repository<br/>[auth.repository.ts]"]
  node_oracle_conn["Oracle connection<br/>[oracle.ts]"]
end

node_user(("User"))
node_oracle[("Oracle database")]

node_user -->|"uses"| node_main_app
node_main_app -->|"renders"| node_dashboard_ui
node_main_app -->|"renders"| node_history_ui
node_main_app -->|"renders"| node_summary_ui
node_user -->|"uses"| node_admin_ui
node_main_app -->|"requests vouchers"| node_voucher_api
node_main_app -->|"uploads files"| node_bulk_api
node_voucher_api -->|"authenticates"| node_auth
node_voucher_api -->|"records job"| node_records_repo
node_voucher_api -->|"looks up vouchers"| node_voucher_repo
node_voucher_api -->|"creates archive"| node_zip_util
node_records_repo -->|"uses connection"| node_oracle_conn
node_voucher_repo -->|"uses connection"| node_oracle_conn
node_oracle_conn -->|"connects"| node_oracle
node_main_app -.->|"downloads"| node_download_service
node_user -->|"signs in"| node_login_api
node_login_api -->|"checks attempts"| node_rate_limit
node_login_api -->|"finds user"| node_auth_repo
node_login_api -->|"creates session"| node_oracle_conn
node_login_api -->|"updates login"| node_auth_repo
node_refresh_api -->|"refreshes session"| node_oracle_conn
node_auth -->|"reads session"| node_oracle_conn
node_dashboard_api -->|"authenticates"| node_auth
node_dashboard_api -->|"queries metrics"| node_oracle_conn
node_history_api -->|"authenticates"| node_auth
node_history_api -->|"queries records"| node_oracle_conn
node_export_api -->|"authenticates"| node_auth
node_export_api -->|"queries records"| node_oracle_conn
node_admin_ui -->|"admin requests"| node_admin_api
node_admin_api -->|"authenticates"| node_auth
node_admin_api -->|"reads and writes"| node_oracle_conn

click node_main_app "https://github.com/cloudmonks-1000/invoice/blob/main/src/App.tsx"
click node_dashboard_ui "https://github.com/cloudmonks-1000/invoice/blob/main/src/ui-pages/Dashboard.tsx"
click node_history_ui "https://github.com/cloudmonks-1000/invoice/blob/main/src/ui-pages/History.tsx"
click node_summary_ui "https://github.com/cloudmonks-1000/invoice/blob/main/src/ui-pages/Summary.tsx"
click node_admin_ui "https://github.com/cloudmonks-1000/invoice/tree/main/app/admin"
click node_dashboard_api "https://github.com/cloudmonks-1000/invoice/blob/main/app/api/dashboard/route.ts"
click node_history_api "https://github.com/cloudmonks-1000/invoice/blob/main/app/api/history/route.ts"
click node_export_api "https://github.com/cloudmonks-1000/invoice/blob/main/app/api/history/export/route.ts"
click node_voucher_api "https://github.com/cloudmonks-1000/invoice/blob/main/app/api/invoices/%5BvoucherNumber%5D/route.ts"
click node_bulk_api "https://github.com/cloudmonks-1000/invoice/blob/main/app/api/invoices/bulk/upload/route.ts"
click node_download_service "https://github.com/cloudmonks-1000/invoice/blob/main/src/services/voucher-download.service.ts"
click node_zip_util "https://github.com/cloudmonks-1000/invoice/blob/main/src/utils/zip.ts"
click node_login_api "https://github.com/cloudmonks-1000/invoice/blob/main/app/api/auth/login/route.ts"
click node_refresh_api "https://github.com/cloudmonks-1000/invoice/blob/main/app/api/auth/refresh/route.ts"
click node_auth_api "https://github.com/cloudmonks-1000/invoice/tree/main/app/api/auth"
click node_auth "https://github.com/cloudmonks-1000/invoice/blob/main/src/auth/auth.ts"
click node_rate_limit "https://github.com/cloudmonks-1000/invoice/blob/main/src/security/login-rate-limit.ts"
click node_admin_api "https://github.com/cloudmonks-1000/invoice/tree/main/app/api/admin"
click node_records_repo "https://github.com/cloudmonks-1000/invoice/blob/main/src/db/repositories/records.repository.ts"
click node_voucher_repo "https://github.com/cloudmonks-1000/invoice/blob/main/src/db/repositories/voucher.repository.ts"
click node_auth_repo "https://github.com/cloudmonks-1000/invoice/blob/main/src/db/repositories/auth.repository.ts"
click node_oracle_conn "https://github.com/cloudmonks-1000/invoice/blob/main/src/db/oracle.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_main_app,node_dashboard_ui,node_history_ui,node_summary_ui,node_admin_ui,node_user toneBlue
class node_dashboard_api,node_history_api,node_export_api,node_voucher_api,node_bulk_api,node_download_service,node_zip_util,node_oracle toneAmber
class node_login_api,node_refresh_api,node_auth_api,node_auth,node_rate_limit,node_admin_api toneMint
class node_records_repo,node_voucher_repo,node_auth_repo,node_oracle_conn toneRose
```

## Components

### User interface

- [Main app](https://github.com/cloudmonks-1000/invoice/blob/main/src/App.tsx): `src/App.tsx`
- [Dashboard UI](https://github.com/cloudmonks-1000/invoice/blob/main/src/ui-pages/Dashboard.tsx): `src/ui-pages/Dashboard.tsx`
- [History UI](https://github.com/cloudmonks-1000/invoice/blob/main/src/ui-pages/History.tsx): `src/ui-pages/History.tsx`
- [Summary UI](https://github.com/cloudmonks-1000/invoice/blob/main/src/ui-pages/Summary.tsx): `src/ui-pages/Summary.tsx`
- [Admin pages](https://github.com/cloudmonks-1000/invoice/tree/main/app/admin): `app/admin`

### Invoice workflows

- [Dashboard API](https://github.com/cloudmonks-1000/invoice/blob/main/app/api/dashboard/route.ts): `app/api/dashboard/route.ts`
- [History API](https://github.com/cloudmonks-1000/invoice/blob/main/app/api/history/route.ts): `app/api/history/route.ts`
- [History export](https://github.com/cloudmonks-1000/invoice/blob/main/app/api/history/export/route.ts): `app/api/history/export/route.ts`
- [Voucher download](https://github.com/cloudmonks-1000/invoice/blob/main/app/api/invoices/%5BvoucherNumber%5D/route.ts): `app/api/invoices/[voucherNumber]/route.ts`
- [Bulk upload](https://github.com/cloudmonks-1000/invoice/blob/main/app/api/invoices/bulk/upload/route.ts): `app/api/invoices/bulk/upload/route.ts`
- [Download service](https://github.com/cloudmonks-1000/invoice/blob/main/src/services/voucher-download.service.ts): `src/services/voucher-download.service.ts`
- [ZIP creation](https://github.com/cloudmonks-1000/invoice/blob/main/src/utils/zip.ts): `src/utils/zip.ts`

### Identity and admin

- [Login API](https://github.com/cloudmonks-1000/invoice/blob/main/app/api/auth/login/route.ts): `app/api/auth/login/route.ts`
- [Session refresh](https://github.com/cloudmonks-1000/invoice/blob/main/app/api/auth/refresh/route.ts): `app/api/auth/refresh/route.ts`
- [Auth routes](https://github.com/cloudmonks-1000/invoice/tree/main/app/api/auth): `app/api/auth`
- [Auth helper](https://github.com/cloudmonks-1000/invoice/blob/main/src/auth/auth.ts): `src/auth/auth.ts`
- [Login rate limit](https://github.com/cloudmonks-1000/invoice/blob/main/src/security/login-rate-limit.ts): `src/security/login-rate-limit.ts`
- [Admin APIs](https://github.com/cloudmonks-1000/invoice/tree/main/app/api/admin): `app/api/admin`

### Oracle persistence

- [Records repository](https://github.com/cloudmonks-1000/invoice/blob/main/src/db/repositories/records.repository.ts): `src/db/repositories/records.repository.ts`
- [Voucher repository](https://github.com/cloudmonks-1000/invoice/blob/main/src/db/repositories/voucher.repository.ts): `src/db/repositories/voucher.repository.ts`
- [Auth repository](https://github.com/cloudmonks-1000/invoice/blob/main/src/db/repositories/auth.repository.ts): `src/db/repositories/auth.repository.ts`
- [Oracle connection](https://github.com/cloudmonks-1000/invoice/blob/main/src/db/oracle.ts): `src/db/oracle.ts`

### Other components

- **User**
- **Oracle database**

## Connections

- User → Main app: uses
- Main app → Dashboard UI: renders
- Main app → History UI: renders
- Main app → Summary UI: renders
- User → Admin pages: uses
- Main app → Voucher download: requests vouchers
- Main app → Bulk upload: uploads files
- Voucher download → Auth helper: authenticates
- Voucher download → Records repository: records job
- Voucher download → Voucher repository: looks up vouchers
- Voucher download → ZIP creation: creates archive
- Records repository → Oracle connection: uses connection
- Voucher repository → Oracle connection: uses connection
- Oracle connection → Oracle database: connects
- Main app → Download service: downloads
- User → Login API: signs in
- Login API → Login rate limit: checks attempts
- Login API → Auth repository: finds user
- Login API → Oracle connection: creates session
- Login API → Auth repository: updates login
- Session refresh → Oracle connection: refreshes session
- Auth helper → Oracle connection: reads session
- Dashboard API → Auth helper: authenticates
- Dashboard API → Oracle connection: queries metrics
- History API → Auth helper: authenticates
- History API → Oracle connection: queries records
- History export → Auth helper: authenticates
- History export → Oracle connection: queries records
- Admin pages → Admin APIs: admin requests
- Admin APIs → Auth helper: authenticates
- Admin APIs → Oracle connection: reads and writes