Add project plan and TODO checklist
This commit is contained in:
+108
@@ -0,0 +1,108 @@
|
||||
# TehRiehlBudget - Project Architecture & Implementation Plan
|
||||
|
||||
**Target Deployment URL:** `https://budget.tehriehldeal.com`
|
||||
|
||||
## 1. Project Overview
|
||||
TehRiehlBudget is a highly secure, comprehensive personal finance application. It allows users to track spending across various account types (savings, checking, credit, loans, stocks), manually input transactions, upload receipt images, and view dynamic financial dashboards. The app features robust data encryption, external institution linking for live tracking, and AI-driven financial insights.
|
||||
|
||||
---
|
||||
|
||||
## 2. Technology Stack
|
||||
* **Frontend:** React (bootstrapped with Vite) utilizing TypeScript.
|
||||
* **UI/Styling:** TailwindCSS paired with ShadCN UI components.
|
||||
* **State Management:** Zustand for lightweight global state (sessions, cached data).
|
||||
* **Backend:** NestJS (TypeScript) for a modular, scalable RESTful API.
|
||||
* **Database:** PostgreSQL for robust relational data mapping.
|
||||
* **Infrastructure/Hosting:** Docker for local containerization, S3-compatible cloud storage for receipt images.
|
||||
|
||||
---
|
||||
|
||||
## 3. Project Environment Setup Steps
|
||||
To get the local development environment running smoothly on your CachyOS system, follow these initialization steps:
|
||||
|
||||
**Prerequisites:** Node.js, your preferred package manager, and Docker.
|
||||
|
||||
**1. Initialize the Backend:**
|
||||
```bash
|
||||
# Generate the Nest application
|
||||
npx @nestjs/cli new tehriehlbudget-backend --strict
|
||||
cd tehriehlbudget-backend
|
||||
|
||||
# Install necessary ORM and encryption utilities (example using Prisma)
|
||||
npm install prisma --save-dev
|
||||
npx prisma init
|
||||
```
|
||||
|
||||
**2. Initialize the Frontend:**
|
||||
```bash
|
||||
# Scaffold the React app with Vite
|
||||
npm create vite@latest tehriehlbudget-frontend -- --template react-ts
|
||||
cd tehriehlbudget-frontend
|
||||
npm install
|
||||
|
||||
# Initialize TailwindCSS and ShadCN UI
|
||||
npx tailwindcss init -p
|
||||
npx shadcn-ui@latest init
|
||||
```
|
||||
|
||||
**3. Database Containerization:**
|
||||
Create a `docker-compose.yml` in the root of your backend project to quickly spin up the PostgreSQL instance without cluttering your host machine:
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:15-alpine
|
||||
environment:
|
||||
POSTGRES_USER: admin
|
||||
POSTGRES_PASSWORD: development_password
|
||||
POSTGRES_DB: tehriehlbudget
|
||||
ports:
|
||||
- "5432:5432"
|
||||
volumes:
|
||||
- pgdata:/var/lib/postgresql/data
|
||||
volumes:
|
||||
pgdata:
|
||||
```
|
||||
Run `docker-compose up -d` to start the database.
|
||||
|
||||
---
|
||||
|
||||
## 4. Security & Authentication Model
|
||||
Due to the sensitive nature of financial data, security at multiple layers is critical.
|
||||
|
||||
* **User Identity:** Implement a dedicated auth provider like Supabase Auth, Clerk, or Auth0. These services handle secure JWT issuance, local email/password setups, and make adding OAuth (Google, GitHub, etc.) seamless while offloading the risk of managing raw passwords.
|
||||
* **Encryption at Rest:** Ensure the production PostgreSQL database volume (whether hosted via AWS RDS, Vercel, or a VPS) has hardware/volume-level encryption enabled by default.
|
||||
* **Field-Level Encryption:** Utilize an application-level encryption interceptor in NestJS (using AES-256-GCM). Highly sensitive database columns (e.g., account numbers, API access tokens, precise transaction notes) must be encrypted in memory before writing to PostgreSQL, and decrypted on retrieval before being sent to the authorized client.
|
||||
|
||||
---
|
||||
|
||||
## 5. Core Third-Party Integrations
|
||||
* **Live Institution Tracking (Plaid):** Integrate the Plaid API to securely link external accounts. This allows the app to fetch real-time balances and transaction histories from established institutions (like BECU, SoFi, Discover, and Robinhood) without ever handling the user's actual banking credentials.
|
||||
* **AI Financial Advisor (OpenAI / Gemini):** Create an endpoint that feeds anonymized, aggregated transaction data to an LLM. The AI will return contextual feedback, spending summaries, and personalized saving advice to be displayed on the user's dashboard.
|
||||
* **File Storage (Self Hosted):** Securely store uploaded receipt images. The NestJS backend will generate pre-signed URLs to allow the frontend to safely upload and retrieve images without exposing the storage bucket directly.
|
||||
|
||||
---
|
||||
|
||||
## 6. Development Roadmap
|
||||
|
||||
### Phase 1: Foundation & Infrastructure
|
||||
* Execute environment setup steps (Vite, NestJS, Dockerized Postgres).
|
||||
* Define base database schemas (Users, Accounts, Transactions, Categories).
|
||||
* Implement user authentication and protected frontend routing.
|
||||
* Configure DNS and SSL for `budget.tehriehldeal.com`.
|
||||
|
||||
### Phase 2: Core Ledger & UI Framework
|
||||
* Build NestJS CRUD endpoints for manual Accounts and Transactions.
|
||||
* Implement the field-level encryption logic for the database layer.
|
||||
* Construct the frontend UI layouts using ShadCN and Tailwind.
|
||||
* Implement Zustand stores to manage account and transaction states across the app.
|
||||
|
||||
### Phase 3: Media, Analytics, & Dashboards
|
||||
* Integrate S3 storage for receipt uploads during the transaction entry flow.
|
||||
* Write aggregation queries to calculate Net Worth, Total Debt, and periodic spending (weekly/monthly).
|
||||
* Build the frontend dashboard with charting libraries (e.g., Recharts) to visualize category breakdowns over time.
|
||||
|
||||
### Phase 4: Advanced Integrations
|
||||
* Implement the Plaid Link flow on the frontend and token exchange on the backend.
|
||||
* Build the synchronization logic to pull live data from external institutions.
|
||||
* Develop the AI integration pipeline, strictly ensuring all PII is stripped from the payload before requesting financial insights.
|
||||
@@ -0,0 +1,112 @@
|
||||
# TehRiehlBudget — TODO
|
||||
|
||||
> **Development approach:** Test-Driven Development (TDD). Write tests before implementation. Target **90%+ code coverage** across both frontend and backend.
|
||||
|
||||
---
|
||||
|
||||
## Test Infrastructure Setup
|
||||
|
||||
- [x] Configure Jest for backend (NestJS) with coverage thresholds (90% statements, branches, functions, lines)
|
||||
- [x] Configure Vitest + React Testing Library for frontend with coverage thresholds (90%)
|
||||
- [x] Add pnpm workspace scripts for running all tests and generating combined coverage reports
|
||||
- [ ] Set up test database configuration (separate Postgres instance or test schema for integration tests)
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Foundation & Infrastructure
|
||||
|
||||
### Project Scaffolding
|
||||
- [x] Initialize pnpm workspace at project root (`pnpm-workspace.yaml`)
|
||||
- [x] Scaffold NestJS backend (`tehriehlbudget-backend/`)
|
||||
- [x] Scaffold React + Vite frontend (`tehriehlbudget-frontend/`)
|
||||
- [x] Create `docker-compose.yml` for PostgreSQL container
|
||||
- [x] Initialize TailwindCSS and ShadCN UI in frontend
|
||||
- [x] Configure shared ESLint and Prettier across the monorepo
|
||||
|
||||
### Database Schema
|
||||
- [x] Write tests for Prisma model validations and relations
|
||||
- [x] Define Prisma schema: `User`, `Account`, `Transaction`, `Category` models
|
||||
- [x] Create initial migration (`prisma migrate dev`)
|
||||
- [x] Seed script for development data
|
||||
|
||||
### Authentication (Supabase Auth)
|
||||
- [x] Write tests for backend JWT guard (valid token, expired token, missing token)
|
||||
- [x] Implement NestJS Supabase Auth guard and middleware
|
||||
- [x] Write tests for frontend auth state management (Zustand store)
|
||||
- [x] Implement frontend Supabase Auth integration (login, signup, logout, OAuth)
|
||||
- [x] Implement protected route wrappers on frontend
|
||||
- [ ] Configure DNS and SSL for `budget.tehriehldeal.com`
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Core Ledger & UI Framework
|
||||
|
||||
### Accounts Module
|
||||
- [x] Write tests for Accounts service (create, read, update, delete, list by user)
|
||||
- [x] Write tests for Accounts controller (request validation, auth, response shape)
|
||||
- [x] Implement Accounts NestJS module (service, controller, DTOs)
|
||||
- [x] Write tests for Accounts Zustand store
|
||||
- [x] Build Accounts UI (list view, create/edit forms) with ShadCN components
|
||||
|
||||
### Transactions Module
|
||||
- [x] Write tests for Transactions service (CRUD, filtering by date/category/account)
|
||||
- [x] Write tests for Transactions controller (request validation, auth, pagination)
|
||||
- [x] Implement Transactions NestJS module (service, controller, DTOs)
|
||||
- [x] Write tests for Transactions Zustand store
|
||||
- [x] Build Transactions UI (list view, create/edit forms, category assignment)
|
||||
|
||||
### Categories Module
|
||||
- [x] Write tests for Categories service (CRUD, default categories per user)
|
||||
- [x] Implement Categories NestJS module (service, controller, DTOs)
|
||||
- [x] Build Categories UI (management page, color/icon assignment)
|
||||
|
||||
### Field-Level Encryption
|
||||
- [x] Write tests for encryption interceptor (encrypt on write, decrypt on read, handle null values)
|
||||
- [x] Write tests for encryption utility functions (AES-256-GCM encrypt/decrypt, key rotation)
|
||||
- [x] Implement NestJS encryption interceptor and utility module
|
||||
- [x] Mark sensitive Prisma fields and apply interceptor to relevant endpoints
|
||||
|
||||
### Frontend Layout
|
||||
- [x] Build app shell layout (sidebar navigation, header, main content area)
|
||||
- [x] Implement responsive design breakpoints
|
||||
- [x] Build shared UI components (data tables, form inputs, modals, toasts)
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Media, Analytics, & Dashboards
|
||||
|
||||
### Receipt Upload
|
||||
- [x] Write tests for file upload service (save to disk, retrieve, delete, size/type validation)
|
||||
- [x] Write tests for upload controller (auth, file validation, access-controlled URL generation)
|
||||
- [x] Implement local filesystem storage service in NestJS
|
||||
- [x] Implement upload/download endpoints with access-controlled URLs
|
||||
- [x] Write tests for receipt attachment in transaction flow
|
||||
- [x] Build receipt upload UI (drag-and-drop, preview, attach to transaction)
|
||||
|
||||
### Financial Aggregations
|
||||
- [x] Write tests for aggregation service (net worth, total debt, weekly/monthly spending by category)
|
||||
- [x] Implement aggregation queries and service module
|
||||
- [x] Write tests for aggregation API endpoints
|
||||
- [x] Implement aggregation endpoints
|
||||
|
||||
### Dashboard
|
||||
- [x] Write tests for dashboard data-fetching hooks
|
||||
- [x] Build dashboard page with Recharts (net worth over time, spending by category, debt breakdown)
|
||||
- [x] Implement date range selectors and filtering controls
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Advanced Integrations
|
||||
|
||||
### Plaid Integration
|
||||
- [x] Write tests for Plaid service (link token creation, token exchange, account sync, transaction sync)
|
||||
- [x] Implement Plaid backend module (link tokens, public token exchange, webhook handler)
|
||||
- [x] Write tests for Plaid Link frontend flow
|
||||
- [x] Build Plaid Link UI (connect account flow, linked accounts management)
|
||||
- [x] Implement sync logic to pull live balances and transactions from linked institutions
|
||||
|
||||
### AI Financial Advisor
|
||||
- [x] Write tests for PII stripping utility (ensure no names, account numbers, or identifiers leak)
|
||||
- [x] Write tests for AI advisor service (prompt construction, response parsing, error handling)
|
||||
- [x] Implement AI advisor endpoint (anonymize data, call LLM, return insights)
|
||||
- [x] Build advisor UI on dashboard (insights card, spending summaries, saving suggestions)
|
||||
Reference in New Issue
Block a user