shorrohs/quiloo

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.