Project Blue — Personal Finance Platform

A goal-driven personal finance platform that helps users track expenses, set financial goals, link investments to goals, manage budgets, and gain actionable insights — all from a mobile-first experience backed by a zero-trust ledger architecture.

---

What It Does

Feature	Description
Home Dashboard	At-a-glance balance, portfolio summary, goal progress cards, and recent transactions
Transactions	Full transaction history with search, date-range filters, source & category filters
Analytics	Income vs. expense breakdowns by category with period selection, drill-down to transactions
Goals	Create, edit, and track financial goals (education, retirement, travel, etc.) with inflation-adjusted projections and SIP/lumpsum recommendations
Goal–Investment Linking	Map portfolio holdings to specific goals and track per-goal investment progress
Portfolio	Net worth overview, individual holding details, returns tracking, and risk profile display
Risk Assessment	Interactive questionnaire to determine user risk profile (Conservative → Very Aggressive)
Budgets	Set monthly spending limits per category
Budget Breach Notifications	Real-time alerts when spending exceeds budget limits
Notifications	Centralized feed for SIP deductions, goal milestones, dividends, and budget alerts
Settings	Budget limit configuration per spending category

---

Architecture

┌──────────────┐       ┌──────────────────┐       ┌────────────────┐
│  Mobile App  │──────▶│   API Gateway    │──────▶│    Ledger      │──────▶ PostgreSQL
│  (Expo/RN)   │       │   :3000          │       │    :3001       │
└──────────────┘       │  JWT Auth        │       │  Append-only   │
                       │  Ownership check │       │  Single writer │
                       │  Reverse proxy   │       │  Idempotent    │
                       └──────────────────┘       └────────────────┘

Zero-Trust Ledger Gateway — the client never writes directly. Every mutation flows through the API Gateway (auth + ownership) to the Ledger service (the single writer to financial data). The Ledger enforces append-only writes with compensating entries for corrections.

Services

Service	Directory	Port	Responsibilities
API Gateway	server/api-gateway/	3000	Supabase JWT auth, ownership enforcement, reverse proxy to Ledger. No DB access.
Ledger	server/ledger/	3001	Single writer to financial data. Append-only, idempotent. Internal-only (X-Internal-Secret).
Mobile App	client/mobile-app/	—	Expo SDK 54, React Native 0.81, NativeWind/Tailwind. Currently uses mock data.
Prototype	proto/	3000	Interactive React/TypeScript UI prototype with all 13 screens. Used for design validation and user-story generation.

Clean Architecture Layers

Both server services follow strict domain/ → application/ → adapters/ → framework/ layering, enforced by AST-based fitness functions in CI.

src/
├── domain/         # Pure business types & rules — no external imports
├── application/    # Use cases — imports domain only
├── adapters/       # External integrations — imports domain + application
└── framework/      # Express, config, middleware — wires everything together

---

Tech Stack

Backend

• Runtime: Node.js (ESM)
• Framework: Express 5
• Language: TypeScript 5.9 (strict mode, nodenext modules)
• Auth: Supabase JWT
• API Spec: OpenAPI 3.0.3 (37+ endpoints defined)
• Deployment: Render.com

Mobile

• Framework: React Native 0.81 + Expo SDK 54
• Styling: NativeWind 4 / Tailwind CSS 3
• Icons: lucide-react-native
• Animations: react-native-reanimated 4
• Language: TypeScript

Prototype

• Framework: React 18 + react-scripts 5
• Styling: Tailwind CSS (CDN)
• Icons: lucide-react
• Language: TypeScript
• Source: Single-file app at proto/src/App.tsx (13 screens)

---

API Overview

Full OpenAPI spec at server/api-gateway/openapi.yaml. Currently live routes serve gateway infra (docs, health, tester). All domain endpoints are spec'd and planned:

Domain	Endpoints	Description
Auth	/auth/login, /auth/refresh	JWT login & token refresh
User	/me	Profile get & update
Transactions	/transactions, /transactions/{id}, /transactions/summary	CRUD + monthly summary
Analytics	/analytics/category-breakdown, /analytics/cashflow, /analytics/trends	Spending & income insights
Goals	/goals, /goals/{id}, /goals/{id}/progress, /goals/{id}/linked-investments	Goal lifecycle + investment linking
Portfolio	/portfolio/summary, /portfolio/holdings, /portfolio/holdings/{id}/performance	Holdings & performance
Risk	/risk-profile, /risk-assessment/submit	Risk profile management
Funds	/funds, /funds/{id}, /recommendations	Fund catalog & recommendations
Budgets	/budgets	Budget limits per category
Alerts	/alerts/budget-breaches	Budget exceeded alerts
Notifications	/notifications, /notifications/{id}/read, /notifications/read-all	Notification feed

---

App Screens

The mobile app includes these screens with full navigation:

Screen	Description
Home	Balance card, portfolio value, goal carousel, recent transactions
Analytics	Donut visualization of income/expense by category, period filter
Transactions	Searchable, filterable transaction list grouped by date
Goals	Goal list with progress bars and "Add New"
Goal Details	Target, SIP amount, time left, linked investments
New/Edit Goal	Category picker, inflation calculator, SIP/lumpsum recommendation engine
Portfolio	Risk profile card, net worth, holdings list
Holding Details	Current value, returns, mapped goals
Risk Assessment	Multi-step questionnaire → profile result
Settings	Monthly budget limits per category
Notifications	Budget breach alerts + activity feed

---

Getting Started

Prerequisites

• Node.js ≥ 18
• npm ≥ 9
• Expo CLI (npx expo)
• iOS Simulator / Android Emulator (or physical device with Expo Go)

Server

cd server
npm ci                          # Install all workspaces
npm run dev --workspaces        # Start both services in dev mode (tsx watch)

API Gateway runs at http://localhost:3000, Ledger at http://localhost:3001.

Mobile App

cd client/mobile-app
npm install
npx expo start                  # Start Expo dev server
# Then press 'i' for iOS or 'a' for Android

Prototype

cd proto
npm install
npm start                       # Opens at http://localhost:3000

The prototype contains all 13 screens: login, home, transactions, goals, portfolio, new-goal, analytics, goal-details, holding-details, risk-assessment, settings, notifications, connect-email.

Build

# Server
cd server
npm run build --workspaces

# Mobile
cd client/mobile-app
npx expo run:ios                # or npx expo run:android

---

Testing & Quality Gates

cd server
npm test                        # Jest across all projects (90% coverage threshold)
npm run fitness:all             # Full fitness gate

Fitness Functions (16 automated invariant checks)

Check	What It Enforces
verify-clean-architecture-imports	Import direction: domain → application → adapters → framework
verify-money-math	No number type for money fields — string / bigint / Decimal only
verify-ledger-invariants	Append-only: no UPDATE / DELETE on ledger_entries
verify-idempotency	All writes require UNIQUE(owner_user_id, idempotency_key)
verify-sql-safety	No string concatenation/interpolation in SQL queries
verify-authorization-completeness	Auth middleware coverage across routes
verify-api-contract	OpenAPI spec valid via swagger-parser + spectral-cli
verify-pii-secrets	No leaked secrets or PII in source
verify-config-hardening	Secure configuration defaults
verify-dependency-policy	Allowed dependency list enforcement
verify-migration-safety	Safe DB migration patterns
verify-outbox-consistency	Transactional outbox pattern compliance
verify-webhook-replay-safety	Idempotent webhook handling
verify-performance-budget	Performance constraint checks
verify-observability-baseline	Logging & monitoring baseline
verify-clean-architecture-project	Project structure validation

---

Code Rules

1. No float money — Never use number for amounts. Use string, bigint, or Decimal.
2. Append-only ledger — ledger_entries supports only SELECT and INSERT. Corrections use compensating entries.
3. Idempotency — All externally-triggered writes require UNIQUE(owner_user_id, idempotency_key).
4. Ownership — Every financial row has owner_user_id NOT NULL, enforced by middleware.
5. No raw SQL — Parameterized queries only.
6. No any — @typescript-eslint/no-explicit-any: error.
7. No floating promises — Every async call must be awaited.
8. ESM only — .js extensions in imports, "type": "module".

---

Naming Conventions

Context	Style	Example
TypeScript code	camelCase	getBalance(), ownerUserId
Types / Interfaces	PascalCase	LedgerEntry, Money
DB columns / API DTOs	snake_case	owner_user_id, idempotency_key
Booleans	isX / hasX / shouldX	isActive, hasPermission
Files	PascalCase.ts	AuthMiddleware.ts, SupabaseAdapter.ts

---

Project Structure

project-blue/
├── README.md
├── render.yaml                     # Render.com deployment config
├── adr/                            # Architecture Decision Records
│   ├── ADR-0001  Zero-Trust Boundary
│   ├── ADR-0004  Ledger & DB Hardening
│   ├── ADR-0007  Backend Architecture & Tech Stack
│   ├── ADR-0009  Clean Architecture Folder Rules
│   └── ADR-0011  Code Style & Linting Standards
├── system/                         # System docs (SLOs, invariants, fitness rules)
├── proto/
│   ├── package.json                # React + react-scripts prototype
│   ├── public/                     # Static HTML entry point
│   └── src/
│       └── App.tsx                 # All 13 prototype screens (single-file)
├── server/
│   ├── package.json                # Workspace root (api-gateway + ledger)
│   ├── jest.config.cjs             # Jest config (3 projects, 90% threshold)
│   ├── api-gateway/
│   │   ├── openapi.yaml            # Full API specification
│   │   └── src/
│   │       ├── domain/
│   │       ├── application/
│   │       ├── adapters/auth/      # SupabaseAdapter
│   │       └── framework/          # Express, routes, middleware, config
│   ├── ledger/
│   │   └── src/
│   │       ├── domain/             # Money type
│   │       └── framework/          # Express server
│   └── scripts/                    # 16 fitness function scripts + tests
└── client/
    └── mobile-app/
        ├── App.tsx                 # Root component
        └── src/
            ├── components/         # BottomNav
            ├── constants/          # Mock data
            ├── screens/            # 11 screen components
            ├── types.ts
            └── utils/

---

Deployment

Deployed to Render.com via render.yaml:

• API Gateway — Node.js web service, auto-discovers Ledger URL
• Ledger — Node.js web service, internal secret for auth
• Supabase credentials configured as environment variables

---

Architecture Decision Records

ADR	Topic
ADR-0001	Zero-Trust Boundary pattern
ADR-0004	Append-only enforcement, compensating entries
ADR-0007	Two-service split, Supabase as infra
ADR-0009	Clean Architecture folder rules & DDD
ADR-0011	Linting, no-float-money, import boundaries

---

License

Private — not open source.