# shorrohs/quiloo architecture

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

- Interactive diagram: https://gitdiagram.com/shorrohs/quiloo
- Repository: https://github.com/shorrohs/quiloo

## Overview

1. **Overall shape**: Quiloo is a Node.js application with a thin server-backed architecture: a REST API and admin/business logic in `src/server.js`, PostgreSQL-backed persistence in `src/db.js` and `db/schema.sql`, and a browser UI served from `src/public/`.

2. **Primary runtime boundary**: The app splits cleanly into three layers:
   - **Client**: static HTML/CSS/JS in `src/public/`
   - **Application server**: Express-style backend in `src/server.js`
   - **Data/services**: PostgreSQL for ledger and config data, plus Supabase Storage for documents and SMTP/Nodemailer for credential reset mail

3. **Ledger engine**: The financial core lives in `src/utils/ledger.js`. Its job is to compute chronological daily simple interest, shifting principal/balance over time, and to format amounts using Indian numbering conventions and INR rules. This is the main domain-specific computation boundary in the repo.

4. **Persistence model**: `db/schema.sql` is the canonical database definition, described in the README as “self-healing.” That suggests schema setup/repair is part of the repository’s intended operational model, not just app code. The database appears to store agreement parameters, ledger records, and related admin-controlled state.

5. **Database access layer**: `src/db.js` is the central server-side persistence adapter. It likely owns the PostgreSQL pool and any CRUD helpers used by the API. This is the point where application code crosses into database I/O, and it is the main coupling point for schema, queries, and transaction-oriented logic.

6. **Admin/auth flow**: The backend includes a secured admin console with default credentials noted in the README and token verification in the server. The architecture implies a privileged path for editing agreement settings, managing transactions, and controlling document operations, separate from standard read-only user views.

7. **Document vault path**: Business documents are stored outside the database in **Supabase Storage**. The server handles upload/search-related API calls, and the browser supports previews and filters. So document handling is a separate storage flow: client upload/view request → server auth/processing → Supabase Storage object persistence → client preview/filtering.

8. **Email/reset integration**: Nodemailer is an external service integration for credential reset or recovery workflows. This sits alongside the admin auth subsystem and is a distinct outbound dependency from the main ledger/database flow.

9. **Frontend responsibilities**: `src/public/index.html`, `css/style.css`, and `js/app.js` provide a static single-page style experience with responsive glassmorphic UI, client-side session handling, file reading/base64 preview support, and filter interactions. The frontend is presentation + interaction logic, not a separate application tier.

10. **Operational and environment boundaries**: `.env` contains database and SMTP secrets, indicating the app depends on runtime configuration for connectivity and mail delivery. `test_db.js` suggests a lightweight database connectivity/validation path for local or deployment checks.

11. **Documentation as architecture source**: `docs/architecture.md`, `docs/implementation_plan.md`, and `docs/walkthrough.md` appear to be the canonical narrative for system design, database layout, and feature sequencing. For diagramming, these docs likely reflect the intended flow more directly than the UI assets.

12. **Notable external services**: The two services that materially affect the architecture are **PostgreSQL/Supabase** for structured ledger/config data and **Supabase Storage** for documents. SMTP is the third external integration, but it is narrower in scope and tied to account recovery rather than the core ledger lifecycle.

Main entry points: [`src/server.js`](https://github.com/shorrohs/quiloo/blob/main/src/server.js) (Server core), [`src/db.js`](https://github.com/shorrohs/quiloo/blob/main/src/db.js) (DB adapter), [`src/public/index.html`](https://github.com/shorrohs/quiloo/blob/main/src/public/index.html) (UI shell), [`docs/architecture.md`](https://github.com/shorrohs/quiloo/blob/main/docs/architecture.md) (Architecture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_public_html["UI shell<br/>static page<br/>[index.html]"]
  node_public_css["Styles<br/>presentation css<br/>[style.css]"]
  node_public_js["App logic<br/>client js<br/>[app.js]"]
end

subgraph group_server["Server"]
  node_server_main["Server core<br/>api server<br/>[server.js]"]
  node_db_adapter["DB adapter<br/>persistence layer<br/>[db.js]"]
  node_ledger["Ledger engine<br/>interest calculator<br/>[ledger.js]"]
  node_admin_auth{{"Admin auth<br/>privileged flow"}}
  node_ledger_api{{"Ledger API<br/>business logic"}}
  node_doc_api{{"Document API<br/>file flow"}}
  node_reset_flow{{"Reset mail<br/>recovery flow"}}
end

subgraph group_data["Data & services"]
  node_schema["Schema<br/>[schema.sql]"]
  node_postgres[("PostgreSQL<br/>database")]
  node_supabase_storage[("Storage<br/>object store")]
  node_smtp["SMTP<br/>mail service"]
  node_env["Runtime config<br/>secrets env<br/>[.env]"]
end

subgraph group_docs["Docs"]
  node_docs_arch["Architecture<br/>design doc<br/>[architecture.md]"]
  node_docs_plan["Plan<br/>implementation doc"]
  node_docs_walkthrough["Walkthrough<br/>usage doc<br/>[walkthrough.md]"]
end

node_public_html -->|"loads"| node_public_css
node_public_html -->|"bootstraps"| node_public_js
node_public_js -->|"calls"| node_server_main
node_server_main -->|"guards"| node_admin_auth
node_server_main -->|"routes"| node_ledger_api
node_server_main -->|"routes"| node_doc_api
node_server_main -->|"triggers"| node_reset_flow
node_ledger_api -->|"computes"| node_ledger
node_ledger_api -->|"reads/writes"| node_db_adapter
node_doc_api -->|"stores"| node_supabase_storage
node_doc_api -->|"indexes"| node_db_adapter
node_reset_flow -->|"sends"| node_smtp
node_db_adapter -->|"connects"| node_postgres
node_schema -->|"defines"| node_postgres
node_server_main -.->|"syncs"| node_schema
node_server_main -->|"reads"| node_env
node_smtp -->|"configures"| node_env
node_docs_arch -.->|"informs"| node_docs_plan
node_docs_arch -.->|"describes"| node_docs_walkthrough

click node_public_html "https://github.com/shorrohs/quiloo/blob/main/src/public/index.html"
click node_public_css "https://github.com/shorrohs/quiloo/blob/main/src/public/css/style.css"
click node_public_js "https://github.com/shorrohs/quiloo/blob/main/src/public/js/app.js"
click node_server_main "https://github.com/shorrohs/quiloo/blob/main/src/server.js"
click node_db_adapter "https://github.com/shorrohs/quiloo/blob/main/src/db.js"
click node_ledger "https://github.com/shorrohs/quiloo/blob/main/src/utils/ledger.js"
click node_schema "https://github.com/shorrohs/quiloo/blob/main/db/schema.sql"
click node_docs_arch "https://github.com/shorrohs/quiloo/blob/main/docs/architecture.md"
click node_docs_plan "https://github.com/shorrohs/quiloo/blob/main/docs/implementation_plan.md"
click node_docs_walkthrough "https://github.com/shorrohs/quiloo/blob/main/docs/walkthrough.md"
click node_env "https://github.com/shorrohs/quiloo/blob/main/.env"

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_public_html,node_public_css,node_public_js toneBlue
class node_server_main,node_db_adapter,node_ledger,node_admin_auth,node_ledger_api,node_doc_api,node_reset_flow toneAmber
class node_schema,node_postgres,node_supabase_storage,node_smtp,node_env toneMint
class node_docs_arch,node_docs_plan,node_docs_walkthrough toneRose
```

## Components

### Client

Static browser interface and client-side interaction logic

- [UI shell](https://github.com/shorrohs/quiloo/blob/main/src/public/index.html): static page · Main browser entry point · `src/public/index.html`
- [Styles](https://github.com/shorrohs/quiloo/blob/main/src/public/css/style.css): presentation css · Responsive UI styling · `src/public/css/style.css`
- [App logic](https://github.com/shorrohs/quiloo/blob/main/src/public/js/app.js): client js · Session handling, previews, and filters · `src/public/js/app.js`

### Server

Application server, auth, admin flows, and business logic

- [Server core](https://github.com/shorrohs/quiloo/blob/main/src/server.js): api server · REST API, admin actions, and request routing · `src/server.js`
- [DB adapter](https://github.com/shorrohs/quiloo/blob/main/src/db.js): persistence layer · PostgreSQL access and query helpers · `src/db.js`
- [Ledger engine](https://github.com/shorrohs/quiloo/blob/main/src/utils/ledger.js): interest calculator · Daily simple-interest and INR formatting logic · `src/utils/ledger.js`
- **Admin auth**: privileged flow · Token verification and protected admin console path
- **Ledger API**: business logic · Agreement and transaction operations built on the ledger engine
- **Document API**: file flow · Upload and search operations for business documents
- **Reset mail**: recovery flow · Credential reset and recovery messaging

### Data & services

Database, storage, and outbound service dependencies

- [Schema](https://github.com/shorrohs/quiloo/blob/main/db/schema.sql): sql schema · Canonical database definition and repair model · `db/schema.sql`
- **PostgreSQL**: database · Structured persistence for agreements, ledger data, and admin state
- **Storage**: object store · Document vault for uploaded files
- **SMTP**: mail service · Outbound credential reset mail delivery
- [Runtime config](https://github.com/shorrohs/quiloo/blob/main/.env): secrets env · Database and SMTP connection settings · `.env`

### Docs

Architecture and implementation documentation

- [Architecture](https://github.com/shorrohs/quiloo/blob/main/docs/architecture.md): design doc · System structure and boundaries · `docs/architecture.md`
- [Plan](https://github.com/shorrohs/quiloo/blob/main/docs/implementation_plan.md): implementation doc · Feature sequencing and implementation roadmap · `docs/implementation_plan.md`
- [Walkthrough](https://github.com/shorrohs/quiloo/blob/main/docs/walkthrough.md): usage doc · End-to-end feature and operational narrative · `docs/walkthrough.md`

## Connections

- UI shell → Styles: loads · The UI shell is styled by the main stylesheet
- UI shell → App logic: bootstraps · The page initializes client-side application behavior
- App logic → Server core: calls · Browser actions invoke the backend API
- Server core → Admin auth: guards · Protected admin paths require token verification
- Server core → Ledger API: routes · Core agreement and transaction requests flow here
- Server core → Document API: routes · Document upload and search requests flow here
- Server core → Reset mail: triggers · Recovery requests send credential reset mail
- Ledger API → Ledger engine: computes · Ledger operations rely on the interest engine
- Ledger API → DB adapter: reads/writes · Business operations persist through the database layer
- Document API → Storage: stores · Uploaded documents are persisted in object storage
- Document API → DB adapter: indexes · Document metadata and lookup state are stored in PostgreSQL
- Reset mail → SMTP: sends · Recovery emails are delivered through SMTP
- DB adapter → PostgreSQL: connects · The adapter manages PostgreSQL access
- Schema → PostgreSQL: defines · The canonical schema governs database structure
- Server core → Schema: syncs · Server-side logic depends on the canonical schema model
- Server core → Runtime config: reads · Runtime configuration supplies secrets and connection settings
- SMTP → Runtime config: configures · Mail delivery depends on environment-provided credentials
- Architecture → Plan: informs · Architecture and implementation plan reinforce each other
- Architecture → Walkthrough: describes · The walkthrough reflects the intended system behavior