first commit

PROJECT_PLAN.md

@@ -0,0 +1,81 @@
+# 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.
+