kaushik.paykoli()fullstack_engineer
// Case Study / High-Integrity Collaborative Finance Protocol

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

Next.js 15TypeScriptMongoDBMongooseNextAuthTailwind CSSResend API
STATUS: DEPLOYED // CDN_OPTIMIZED
KOSH Group Ledger Showcase Banner
// 01 / The Friction

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.

// 02 / System Design

System Architecture & Flows

Direct client-side visual model mapping of data transactions, lifecycle schemas, and event hooks.

Loading System Architecture...
// 03 / The Post-Mortem

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.

// 04 / Core Logic

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.

// 05 / Visual Telemetry

Production Screenshots & Gallery

Select and maximize thumbnails below to audit raw workspace interfaces and active dashboards.

active_workspace_preview.png
KOSH Platform Homepage
Click to expand

KOSH Platform Homepage: Fintech landing page establishing platform trust, savings mechanics, and security parameters.

// 06 / Features Matrix

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.

// 07 / Post-Mortem Lessons

Lessons & Engineering Retrospectives

// 01 / WHAT WENT WELL

System Successes

Reframing the app around schema mechanics and state security worked perfectly, proving full-stack integrity during interviews.

// 02 / IMPROVEMENT BOUNDS

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.

// 03 / SYSTEM MINDSET

Operational Learnings

State management in collaborative applications is difficult. Relational models in document databases require defensive validation to prevent data anomalies.