tabungin/docs/planning/project-plan.md

Tabungin — Cross‑Platform Final Plan (v1)

Last updated: 11 Aug 2025

---

1) Executive summary

Goal: Build a simple but flexible cross‑platform personal finance app (web, desktop via Tauri, Android via Tauri Mobile) with a freemium model. Core features: money wallets, transactions (incl. recurring), basic reports. Premium priorities (in order): Assets, Exports, API/Webhooks.

Principles: One backend for all clients; one shared UI + core logic; thin platform shells; OIDC-based login that works everywhere; data consistency within 10s across devices. Keep the stack lean to avoid unnecessary complexity or startup‑scale overhead.

---

2) Architecture overview

• Clients:
  • Web SPA (client-side pages) / optional PWA
  • Desktop app (Tauri) for Win/macOS/Linux
  • Android app (Tauri Mobile); iOS later if needed
• Shared packages:
  • packages/core — domain models, currency math, recurrence engine, validations (TS)
  • packages/ui — React components/screens, theming, accessibility
• Backend: NestJS (Node + TypeScript). REST API with typed SDK. Jobs/queues for recurring txns, price updates, exports, and notifications.
• Database: PostgreSQL (self‑hosted on Coolify) — no reliance on 3rd‑party DB vendors.
• Auth: OIDC via Supabase Auth (cost‑effective, quick to set up) with mapping to our own users table for vendor independence.
• Notifications: In‑app center + Email; other channels (Web Push, Desktop OS, Android Push) can be added later.

---

3) Technology choices (finalized for v1)

• Frontend: React + Tailwind CSS.
• Desktop/Mobile shell: Tauri v2.
• Backend framework: NestJS — opinionated structure, modular, maintainable.
• ORM & schema: Prisma — type‑safe queries, smooth migrations.
• Database hosting: Self‑hosted PostgreSQL on Coolify.
• Email delivery: Elastic Email (API-based) with backend webhook support for bounces/complaints; fallback to SMTP if desired.
• Charting library: Recharts.
• Export libraries: CSV (built‑in first), Excel (ExcelJS, later), PDF (Playwright for server‑side render, later).
• Jobs/queues: pg-boss (Postgres‑based) — minimal extra infra.
• Object storage: Not needed for v1 (direct downloads); S3‑compatible (e.g., Cloudflare R2) later.
• Error tracking: Optional for v1; add Sentry when in public beta.
• Date/time & validation: date‑fns (+TZ) and Zod.

---

4) Single‑Dev Lean Mode Workflow

Purpose: Deliver a usable cross‑platform MVP quickly without committing to full “startup‑scale” complexity.

Keep for v1:

• Web SPA as the first client; desktop shell added once web is stable.
• NestJS backend + Prisma with Postgres on Coolify.
• Supabase Auth (OIDC) → local users table mapping.
• In‑app notifications.
• Elastic Email API for critical notices.
• CSV export (inline download).
• Simple recurring engine (pg-boss).

Defer to later:

• Mobile shell (after desktop parity).
• Push notifications (Web, Desktop OS, Android FCM).
• PDF/Excel exports.
• Object storage.
• Public API + webhooks.
• Sentry and advanced monitoring.

Benefit: Lower development overhead, fewer vendors, faster iteration. All deferred features are planned so they can be slotted in without re‑architecture.

---

5) Roadmap & acceptance criteria

• Phase 1: Web MVP (auth, wallets, transactions, recurrences, basic reports, CSV export, email notices).
• Phase 2: Desktop app (Tauri) with parity.
• Phase 3: Android app (Tauri Mobile) with local notifications.
• Phase 4: Premium features (Assets → Exports → API/Webhooks) + extra notification channels.

---

6) Next steps

1. Finalize Elastic Email API integration + webhook handling.
2. Prepare sprint‑ready tickets for Phase 1.
3. Implement in Lean Mode, keeping deferred features behind flags for future expansion.