01. Problem & Opportunity

Debt is uniquely stressful because it is often invisible, scattered across multiple credit cards or lenders, and heavily dependent on shifting deadlines. Traditional financial tracking applications treat debt as a subset of daily budgeting, burying long-term obligations under micro-transactions like daily coffee or grocery logs. This creates significant friction across two primary user groups:

• For Individuals: A distinct lack of clarity surrounding total financial exposure, high mental tracking overhead across multiple obligations, and an elevated risk of missed or delayed payments.

• For Small Businesses: Cash flow instability stemming from unpaid invoices, alongside inefficient manual tracking that directly translates to missed deadlines and strained business relationships.

Overall Impact: Traditional tracking formats introduce heavy cognitive stress, social friction, and operational inefficiency.

02 The Functional Experience

To transform complex financial structures into an approachable, anxiety-reducing daily tool, the user interface is mapped across three core Operational Zones:

The Aggregated Dashboard

A single master view engineered to instantly calculate total outstanding financial exposure across all accounts. It features:

• Upcoming Alerts: A rolling 30-day "Upcoming Payments" list to help users proactively plan cash flow.

• Urgency Flags: Overdue debts are visually surfaced using high-contrast semantic indicators for immediate prioritisation.

• Real-Time Progress: Integrated payment logs and visual progress bars (e.g., "45% Paid") that dynamically reflect repayment strides.

03 Data Architecture & Relational Engineering

To map real-world financial contracts into a NoSQL document database, the storage engine relies on a strictly structured entity topology optimised for scale and performance.

Optimised Relational Mapping

The backend implements a hierarchical One-to-Many-to-Many data architecture, structurally enhanced via database denormalisation:

• User ➔ Debt: A 1:N relationship isolating individual profile entities from distinct liabilities.

• Debt ➔ Payment: A 1:N transactional sub-tier tracking incremental payoff events over time.

• The Optimisation Link (Denormalisation): Storing a copy of the parent user_id reference directly inside individual payment documents represents an intentional performance choice. In high-traffic environments, this layout bypasses multi-stage database aggregation lookups. The system pulls a user's entire payment audit history in a single query step, keeping dashboard queries lightweight and responsive as history records scale.

Database Schema Constraints

• Deterministic Enums: Loan categories and frequency behaviours are strictly bound via enums at the database boundary. This serves as the system's first line of defence, dropping malformed payloads early and preventing database storage corruption.

• Automated Audit Logging: Every system document utilises managed engine timestamps ({ timestamps: true }). This enforces native generation of creation and modification dates to seamlessly feed the visual analytical pipelines without introducing manual logging overhead to controllers.

• Outbound Privacy Masking: To implement defensive security-by-default, the database models employ data-serialisation intercepts. Any outbound data stream is mathematically scrubbed at the model layer to strip credential hashes before information ever leaves the server bounds or crosses the network.

04 Perimeter Security & Business Logic Lifecycles

DebtFlow enforces a zero-trust, stateless security perimeter designed around data privacy and cryptographic access control.

Stateless Identity Management

Rather than storing stateful sessions inside server memory, the application uses a distributed cryptographic handshake model.

• One-Way Cryptographic Hashing: User passwords undergo heavy cryptographic salting with 12 execution rounds using bcrypt. This creates computationally secure hashes that protect user identities even if raw database tables are exposed.

• Stateless Gateway Inspection: API gatekeepers guard all private transaction spaces, validating incoming JSON Web Tokens (JWT) at the network layer. Requests containing missing, tampered, or expired signatures are immediately blocked and returned as unauthorized failures, insulating internal application clusters from unwanted traffic.

• Deep Access Token Isolation: To prevent parameter-tampering attacks (where a malicious user modifies an ID inside an address bar to scrape data), the frontend never transmits the user identifier via URL paths. Instead, identity is extracted securely on the backend from the cryptographically verified JWT payload. The system forces all downstream database queries to filter records exclusively against this server-verified value.

The Principle of Atomic Consistency

Core controller layouts process financial logic as tightly bound, interdependent lifecycles rather than fragmented individual updates. Financial operations require that changes to separate ledger collections succeed together or fail together. When a repayment occurs, the system executes strict atomic logic:

1. Input & Guardrail Verification: The server ensures structural validity and strictly confirms that the asset being modified is explicitly owned by the authenticated caller. If ownership checks fail, a forbidden entry block is thrown immediately.

2. Synchronous Ledger Updates: The payment ledger record is created, and the parent debt's outstanding balance is modified inside the same request cycle. Status changes (such as flipping an item to fully paid off) trigger automatically based on real-time balance calculations, maintaining a single, accurate source of truth.

Mathematical Modification Delta & Purge Cascades

• Delta Adjustment: When a user corrects a previous transaction value, the business logic calculates the absolute delta difference between the old and new states. Utilising database increment operators ($inc), this math corrects balances accurately in both directions—either reducing the remaining balance further or returning funds to the liability if a payment size was reduced.

• Transaction Reversals: Deleting a transaction forces a reverse transaction flow, looking up the historical value first and adding it back to the liability balance to protect historical calculations from corruption.

• Cascade Purges: Account closures trigger a synchronised delete cascade. The system targets and drops all child debts and payments linked to that user profile simultaneously, satisfying privacy standards and eliminating fragmented, orphaned data.

The Insights Engine

An analytical workspace dedicated to breaking down debt by category concentration (Mortgage, Loans, Credit) to identify which liabilities dominate the user's financial profile. It organises data by frequency-based planning cycles (Monthly vs. Annual) to streamline long-term forecasting.

Secure Access Portals

A private ecosystem enabling secure registration and login. This ensures that sensitive liability records remain entirely isolated, confidential, and restricted to the verified account owner.

05 Client-Side Architecture & UI Mechanics

Cascading State Hierarchies

The global application state is organised in a top-down architecture where data flows sequentially from the most critical layer down to dependent modules:

1. Identity Engine (Root / UserProvider): Confirms valid authentication context.

2. Liability Engine (Middle / DebtProvider): References the active identity context to pull authorised accounts.

3. Transactional Engine (Leaf / PaymentProvider): Listens to liabilities and pushes ledger corrections back up, forcing real-time dashboard calculations to stay updated.

Dual-Layer Route Protection

Client routes use dual validation barriers. The browser evaluates active memory states to catch unauthorised attempts early and route users back to login screens before layout elements load. If a malicious client directly manipulates browser states to reveal pages, the secondary backend API layer serves as an absolute barrier, instantly rejecting any data requests that lack an authenticated signature.

Accessibility & Visual Psychology

Managing liabilities is emotionally taxing; therefore, the visual styling was designed to reduce user anxiety through deliberate structural patterns:

• Component Architecture: A clean, dashboard-style UI utilising a modular, card-based layout keeps information organised into highly digestible blocks.

• Colour Psychology System: Visual states are reinforced by a semantic, universally recognised colour palette: Red automatically surfaces urgent overdue items, Green indicates active or fully resolved statuses, and neutral Blue flags educational insights.

• Micro-Typography Adjustments: Clean, wide-spaced headers paired with bold, glanceable numeric values ensure a user can accurately audit their global financial standing in a fraction of a second.