# 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.