Ring-It

A personal finance operating system for Malaysians. Not a tracker. A system built around behavioral friction, double-entry bookkeeping, and local compliance.

---

The Problem

Most budgeting apps show you data. They do not change your behaviour. You log a bad purchase, feel nothing, and do it again next week.

Ring-It is built around three behavioural levers: friction before impulsive purchases, immediate compounding projections after every saving, and a daily reset that makes every day a fresh start. The dark industrial UI is intentional too. Your finances should feel serious.

---

What It Does

Feature	Detail
Ledger Engine	Double-entry bookkeeping under the hood, every transaction is an entry pair
Compounding Preview	Every saving instantly shows a 10-year projection
DSR Calculator	Debt Service Ratio calculator for loan planning
Zakat and Tax	Internal Nisab and LHDN relief calculations
Receipt Vault	Cloudinary upload

---

Stack

Frontend — Vue 3, Vuetify 3 (Sovereign dark theme), Pinia, TypeScript, Tailwind CSS, Axios

Backend — FastAPI, Pydantic v2 (strict mode), SQLAlchemy 2, Alembic, APScheduler, Python 3.12

Database and Auth — Supabase (PostgreSQL, RLS, Auth)

Security — JWT RS256, AES-256-GCM field encryption, rate limiting via slowapi

Storage — Cloudinary (signed upload, encrypted receipts)

Deployment — Vercel (frontend), Railway (backend Docker container), Supabase Cloud

Why this combo:

• Pydantic v2 strict mode with Decimal only, no floats anywhere near money
• Supabase RLS enforces data isolation at DB layer, less middleware to maintain
• APScheduler handles annual policy migration cron on Jan 1st internally, no external cron service
• All LHDN, EPF, and Zakat constants are Admin-maintained Policy Config JSON files, no government API dependencies

---

Project Structure

ring-it/
├── backend/
│   └── app/
│       ├── core/          # JWT, AES encryption, rate limiting, scheduler
│       ├── api/v1/        # FastAPI routers
│       ├── models/        # SQLAlchemy ORM models
│       ├── schemas/       # Pydantic v2 request/response
│       ├── services/      # Business logic (LedgerSvc, DebtNettingEngine, ZakatEngine)
│       └── repositories/  # DB access layer
│   ├── alembic/           # DB migrations
│   └── tests/             # pytest, >90% coverage target
│
└── frontend/
    └── src/
        ├── components/    # VaultDashboard, QuickLogModal, DSRCalculator, AIAdvisorWidget
        ├── pages/         # landingPage, dashboard, transactions
        ├── stores/        # useTransactionStore, useAccountStore, useBudgetStore (Pinia)
        ├── types/         # TypeScript interfaces
        └── plugins/       # vuetify.ts (Sovereign theme)

---

Running Locally

Prerequisites

• Python 3.12+
• Node.js 20+
• A Supabase project at supabase.com
• A Cloudinary account at cloudinary.com

Backend

cd backend
cp .env.example .env
# Fill in Supabase, Cloudinary, and JWT secrets

poetry install
alembic upgrade head
uvicorn app.main:app --reload --port 8000
# Swagger: http://localhost:8000/docs

Frontend

cd frontend
cp .env.example .env.local
# Set VITE_API_BASE_URL and Supabase keys

npm install
npm run dev
# App: http://localhost:5173

Docker (Full Stack)

docker compose up --build
# Backend :8000  |  Frontend :5173  |  DB :5432

---

Environment Variables

backend/.env

SUPABASE_URL=
SUPABASE_ANON_KEY=
SUPABASE_SERVICE_KEY=
SECRET_KEY=                  # RS256 private key, min 32 chars
ALLOWED_ORIGINS=http://localhost:5173
CLOUDINARY_CLOUD_NAME=
CLOUDINARY_API_KEY=
CLOUDINARY_API_SECRET=

frontend/.env.local

VITE_API_BASE_URL=http://localhost:8000/api/v1
VITE_SUPABASE_URL=
VITE_SUPABASE_ANON_KEY=

Do not commit .env files. Already in .gitignore.

---

CI/CD

Push to develop or main
  Stage 1: Code Quality    ruff, mypy --strict, vue-tsc, eslint
  Stage 2: Tests           pytest --cov (>90%), vitest --coverage
  Stage 3: Security        pip-audit, npm audit, trivy image scan
  Stage 4: Deploy          Railway (backend), Vercel (frontend) — main branch only

Interface

What I Learned

• Pydantic v2 strict mode with Decimal types catches a whole class of money-rounding bugs before they reach the DB
• Double-entry bookkeeping as a schema pattern makes balance calculations trivial and audits clean
• Behavioral friction as a UI pattern is surprisingly effective even when you know it is there
• APScheduler inside FastAPI is good enough for annual policy cron at this scale, no need for Airflow

---

What Needs Improving

• OCR for receipt scanning is still manual upload, no auto-extraction yet
• AI Advisor widget is a placeholder, needs actual LLM integration
• No mobile app, currently web-only with responsive layout
• Policy Config JSON is Admin-only, no self-service update flow for users yet

---

Docs

Document	Standard	File
Software Requirements Spec	IEEE 830-1998	docs/RING-IT-SRS-001-v1.0.docx
Software Design Document	IEEE 1016-2009	docs/RING-IT-SDD-001-v1.0.docx
API Reference	OpenAPI 3.1	/docs once backend is running

---

Built for Malaysians who want their finances to work as hard as they do.

          ██████╗ ██╗███╗   ██╗ ██████╗       ██╗████████╗
          ██╔══██╗██║████╗  ██║██╔════╝       ██║╚══██╔══╝
          ██████╔╝██║██╔██╗ ██║██║  ███╗█████╗██║   ██║   
          ██╔══██╗██║██║╚██╗██║██║   ██║╚════╝██║   ██║   
          ██║  ██║██║██║ ╚████║╚██████╔╝      ██║   ██║   
          ╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝ ╚═════╝       ╚═╝   ╚═╝