KOSH Group Ledger
A full-stack Susu-style collaborative savings platform. Engineered to enforce strict monthly contribution windows, automated late payment penalties, and state mutation locks to guarantee ledger consistency.
Tech Stack

The Problem & Target Constraints
Traditional savings circles (like susu funds or chit funds) rely on social pressure and spreadsheets to collect monthly funds and distribute payouts. This is prone to human error, missed payments, lack of transparency, and administrative fraud.
Real-World Impact: If a member pays late or misses a month, the total pool shrinks, delaying payouts and causing social friction. If an admin deletes the group prematurely, members lose their capital.
System Architecture & Flows
Direct client-side visual model mapping of data transactions, lifecycle schemas, and event hooks.
Deep-Dive Engineering Challenges
Below is a structured breakdown of the difficult constraints and tradeoffs resolved during the design phase.
Challenge 01: Enforcing Strict Contribution Windows & Penalty Rules
SYSTEM_STABILITY: ACTIVE// The Problem
Allowing members to pay anytime breaks the savings circle payout cycle. We needed to enforce scheduled monthly contribution windows and calculate late-payment penalty logic dynamically.
// Why It Was Difficult
Handling timezone differences, leap years, and database triggers to calculate late penalties up to 40% without bloating database write processes.
// The Solution
Engineered schema logic where contribution windows are pre-calculated during campaign initialization. When a contribution is written, the schema computes the delta between the target window deadline and current timestamp, applying a sliding penalty if late.
// Pragmatic Tradeoffs
Requires rigid campaign configuration during setup (members cannot edit deadlines mid-campaign), but guarantees financial integrity and prevents pool manipulation.
Challenge 02: Preventing Premature Capital Liquidation
SYSTEM_STABILITY: ACTIVE// The Problem
If a group admin deletes their account or group database collections while capital is locked in active campaigns, members lose their funds.
// Why It Was Difficult
Next.js API route handlers must block account deletion requests if active database links exist across different collections.
// The Solution
Implemented strict transactional database hooks. The deletion route verifies if a user owns groups with active campaigns. If true, the database throws, the server aborts the request, and forces the admin to liquidate the pool and delete the group first.
// Pragmatic Tradeoffs
Increases code path complexity for deletion triggers, but enforces absolute security and zero-loss guarantees for user capital.
Challenge 03: NextAuth JWT Session Synchronization
SYSTEM_STABILITY: ACTIVE// The Problem
When a user deposits money and updates their wallet balance, the NextAuth session JWT cookie does not update automatically, causing visual balance discrepancies.
// Why It Was Difficult
Force-refreshing the browser is poor UX, while polling the database on every route wastes MongoDB read bandwidth.
// The Solution
Designed a custom JWT callback in NextAuth linked to a client-side Zustand store. State updates trigger NextAuth's update() method, synchronizing session state in the background without full-page reloads.
// Pragmatic Tradeoffs
Increases client-side state synchronization logic, but creates a seamless, low-latency financial interface.
Architecture & Execution Decisions
// Core Pipeline Design
KOSH is engineered with a strict document schema mapping User, Wallet, Group, and Contribution collections. NextAuth manages session persistence via JWT tokens. Next.js API Routes validate mutations using Zod, writing records via Mongoose. The database schema enforces that contribution values write directly to the user's Wallet collection and the group's Campaign collection simultaneously, maintaining transaction logs.
// Interface Orchestration
The admin coordinates the campaign lifecycle: member approval -> initialization -> active contribution windows -> final payout execution. This mirrors real-world traditional savings structures.
// Media & Memory Bounds
Transactional consistency is enforced by Mongoose validation schemas, which guarantee that deposits cannot exceed wallet balances and withdrawal requests must match the exact payouts calculated by the penalty engine.
Production Screenshots & Gallery
Select and maximize thumbnails below to audit raw workspace interfaces and active dashboards.

KOSH Platform Homepage: Fintech landing page establishing platform trust, savings mechanics, and security parameters.
Detailed Technical Highlights
Campaign State Machine
Strict state flow transitions: Draft -> Active -> Closed -> Payout -> Liquidated.
Contribution Schedules
Scheduled monthly contribution windows calculating late payment penalties capped at 40%.
Zero-Leak Mutability
Mongoose database transactional rules preventing premature group deletion during active campaigns.
Lessons & Engineering Retrospectives
System Successes
Reframing the app around schema mechanics and state security worked perfectly, proving full-stack integrity during interviews.
Areas to Optimize
Integrating real payment gateways (such as Stripe or Plaid) would make this a viable production SaaS, but requires legal and compliance registration.
Operational Learnings
State management in collaborative applications is difficult. Relational models in document databases require defensive validation to prevent data anomalies.