Villa Mutiara Sepakat Financial Management System (SiKas)

Background

Managing community finances in a residential complex is traditionally handled through manual ledgers and spreadsheets—a process prone to errors, opacity, and disputes among residents. Villa Mutiara Sepakat, a housing complex with multiple blocks and hundreds of units, needed a modern, transparent, and accountable system to track monthly dues, operational expenses, and generate trustworthy financial reports for the community.
This project was built to digitize and automate the entire financial workflow for the complex's treasurer (bendahara), replacing manual bookkeeping with a reliable web-based system.

Solution

I designed and developed **SiKas** (Sistem Kas) — a full-stack web application that serves as the single source of truth for all community financial operations. The system features two main surfaces:

Public Landing Page — An SEO-optimized, beautifully designed website for the housing complex featuring community information, facilities showcase, and resident announcements.
Admin Dashboard — A secured, role-based management panel for the treasurer to manage houses, record payments, track expenses, manage announcements, and generate detailed financial reports.
The core innovation is the **carry-over payment allocation algorithm** — when a resident makes a single payment, the system automatically allocates the amount to the oldest unpaid months first, carries surplus forward to future months, and computes payment status (Paid, Partial, Unpaid) in real time. This eliminates manual tracking of partial and advance payments.

The core innovation is the carry-over payment allocation algorithm — when a resident makes a single payment, the system automatically allocates the amount to the oldest unpaid months first, carries surplus forward to future months, and computes payment status (Paid, Partial, Unpaid) in real time. This eliminates manual tracking of partial and advance payments.

Architecture

The application follows a monolithic full-stack architecture using Next.js 16 with the App Router pattern:

Frontend: React 19 with Server Components and Client Components, using route groups `(landing)` for the public site and `(dashboard)` for the admin panel.
Backend: Next.js API Routes serve as the REST API layer, with a clean service-layer pattern (`lib/services/`) separating business logic from route handlers.
Database: PostgreSQL via Neon Serverless Postgres, with Prisma ORM for type-safe database access and migrations.
Authentication: Custom JWT-based authentication with bcrypt password hashing, HTTP-only cookies, and server-side auth guards.
State Management: TanStack React Query for server state caching, invalidation, and optimistic updates.
Security: Rate limiting (auth, API, export endpoints), CORS middleware, comprehensive security headers (CSP, HSTS, X-Frame-Options), and structured logging with Pino.

Key Features

Smart Dashboard: Real-time financial overview with animated stat cards showing current balance, total income, total expenses, and unpaid houses — with month-over-month trend indicators.
Carry-Over Payment System: Intelligent payment allocation engine that automatically distributes payments across multiple months with a live simulation preview before submission.
House Management: Full CRUD operations for housing units with block organization, support for single and batch creation (up to 100 units at once), and real-time payment status tracking per unit.
Expense Tracking: Categorized expense management with dynamic category CRUD, monthly filtering, and animated slide-out panel for data entry.
Financial Reporting Suite: Four report types (Monthly Financial, Payment Details, Annual Recap, Individual Dues Card) with on-screen preview rendered as a styled document, plus one-click export to PDF (via `@react-pdf/renderer`) and Excel (via ExcelJS).
Announcement System: Content management for resident announcements with publish/draft status, displayed on the public landing page with smooth scroll animations.
Opening Balance Configuration: Singleton record management for setting the initial balance before the system was adopted, ensuring accurate running totals.
SEO & Performance: Full structured data (JSON-LD), Open Graph, Twitter cards, sitemap, robots.txt, Web App Manifest, optimized fonts (Google Fonts with preconnect), and security-hardened headers.

Challenges & Learnings

Carry-Over Algorithm Complexity: Designing the payment allocation logic to handle edge cases — partial payments spanning multiple months, retroactive payments for past-due months, and advance payments for future months — required careful algorithmic design with extensive testing.
Real-Time Preview Without Race Conditions: Implementing the carry-over preview that updates as the user types required debouncing, React Query dependency tracking, and handling of the `excludePaymentId` parameter for edit scenarios to avoid double-counting.
Report Generation at Scale: Generating pixel-perfect PDF reports server-side with React PDF and Excel workbooks with ExcelJS in Next.js API routes required careful configuration of server-external packages and memory management.
Responsive Side-Panel UX: Building the animated slide-out panels for forms (using Framer Motion spring physics) while maintaining keyboard accessibility (Escape to close), body scroll locking, and proper focus management.

Results

Replaced 100% of the manual paper-based bookkeeping process with digital records.
Payment processing reduced from ~5 minutes per transaction (manual ledger lookup, calculation, entry) to under 30 seconds with automatic carry-over allocation.
Four types of financial reports can be generated and exported in seconds, versus hours of manual compilation.
The public landing page provides transparent community information accessible 24/7.