Fiku

Zero-Knowledge Personal Finance Platform

Log Quickly, Master Your Personal Finances with End-to-End Encryption

Fiku is a modern web-based personal finance management platform built with Next.js 16, TypeScript, Tailwind CSS v4, and PostgreSQL (Drizzle ORM). All monetary amounts, wallet balances, and financial notes are secured using an end-to-end Zero-Knowledge Encryption architecture (ECIES Asymmetric Encryption with X25519 + AES-256-GCM).

---

📁 Repository Structure

fana/
├── main/              # Main application source code (Next.js 16 Web App, Server Actions, DB, Crypto)
│   ├── app/           # Next.js App Router (/login, /transaction, /summary, /settings, /)
│   ├── components/    # UI components (Spreadsheet UI, Modals, Navbar, Charts)
│   ├── db/            # Drizzle ORM schema definitions (PostgreSQL)
│   ├── lib/           # Business logic, Zero-Knowledge cryptography, i18n, Smart Input
│   ├── public/        # Static assets, brand logos & icons
│   ├── scripts/       # Automation scripts (db-sync, db-reset, seed-dummy)
│   └── package.json   # Next.js & Bun dependencies
├── docs/              # Comprehensive technical documentation
│   ├── ARCHITECTURE.md # System architecture overview & Zero-Knowledge encryption flow
│   ├── DATABASE.md     # Database table schemas & data models
│   ├── DEPLOYMENT.md   # Deployment guide for Vercel & environment variables
│   ├── SMART_INPUT.md  # Quick entry syntax guide for Smart Input (ID & EN)
│   └── COMMANDS.md     # CLI commands and task runner reference
├── tests/             # Unit and integration test suites (Bun test runner)
│   ├── unit/          # Crypto, currency formatting, date summary calculations
│   └── integration/   # Smart natural language input parsing, pagination logic
├── ops/               # Task runner & automatic synchronization
│   ├── workflow.py    # Python runner & .env sync between root <-> main/.env
│   └── pyproject.toml # Ops runner configuration
├── package.json       # Root task runner forwarding commands
├── .gitignore         # Git ignore rules
└── .env.example       # Environment variables template

---

🚀 Key Features

1. Live Interactive Spreadsheet (/transaction):

   • Google Sheets-like spreadsheet experience running directly in the browser.
   • Instantly edit transaction date, type (income/expense/transfer), category, wallet/account, amount (dynamic thousand-separated formatting), and notes with debounced auto-save.
   • Automatic balance validation to prevent spending exceeding the available wallet balance.
   • Server-side pagination with sorting, search query filtering, and configurable page limits (10, 25, 50, 100).
   • Bulk Excel (.xlsx) transaction import & export.

2. Bilingual Smart Natural Language Input:

   • Lightning-fast entry in both Indonesian and English without multi-step forms.
   • Examples: -25k grilled chicken bca, +5m monthly salary mandiri, tf 100k bca to gopay, -35k sayur cash, move 50k gopay to cash.

3. Zero-Knowledge Encryption:

   • Wallet balances (balance), transaction amounts (amount), and notes (note) are encrypted client/server-side using the user's unique public key (X25519).
   • Stored in PostgreSQL as ciphertext payloads (enc:v1:...). Database administrators or unauthorized third parties cannot read users' monetary figures or financial descriptions.
   • Private keys are protected using a combination of the user's password + per-user salt + server pepper + master application secret key, and are stored in a stateless, sealed HTTP-only cookie vault for serverless resilience throughout active sessions.

4. Realtime Visual Financial Summary (/summary):

   • Flexible time period filtering: Daily, Weekly, Monthly, and Yearly.
   • Accumulated balance metrics, total income, expenses, net surplus/deficit, cash flow trend charts, and category expense distribution breakdowns.

5. User Settings & Multi-Currency (/settings):

   • Global currency configuration (IDR, USD, EUR, SGD, JPY, GBP, AUD, CNY, MYR) reflecting throughout the UI and reports.
   • Denormalized transaction count cache stored in user_settings to eliminate expensive full-table scans.

6. Interactive Sandbox on the Homepage (/):

   • Prospective users can immediately try out the live spreadsheet and interactive summary directly on the landing page without signing up.

---

🛠️ Local Development

All commands can be run directly from the repository root using bun run. Environment variables are automatically synchronized between root .env and main/.env.

Prerequisites:

• Bun (bun >= 1.4)
• uv (Python package runner for ops workflow runner)

Quick Start:

# 1. Setup environment variables
cp .env.example .env

# 2. Install dependencies & sync database
bun run install:main
bun run db:sync

# 3. Start development server
bun run dev

Open http://localhost:3000 in your browser.

For the complete list of scripts, testing commands, and database tasks, see docs/COMMANDS.md.

---

🤝 Contributing

We welcome community contributions! To maintain code quality and production stability:

• All Pull Requests must target the staging branch. Direct PRs to main are restricted.
• Review our complete step-by-step setup, coding conventions, and branching workflow in: 👉 Contributor Guide (docs/CONTRIBUTIONS.md)

---

📚 Technical Documentation

For in-depth architectural and module details:

• System Architecture
• Database Schema & Models
• CLI Commands Reference
• Smart Input Guide
• Deployment Guide
• Contributor Guide