Silent Spend Tracker

A subscription and micro-charge detection application that helps users identify and manage small, recurring, or forgettable expenses that accumulate over time.

Project Structure

This is a monorepo containing three packages:

silent-spend-tracker/
├── packages/
│   ├── shared/          # Shared TypeScript types and schemas
│   ├── backend/         # Express.js API server
│   └── frontend/        # React web application
├── .env.example         # Environment variables template
└── package.json         # Root package configuration

Prerequisites

• Node.js 20+ and npm
• AWS Account with CLI configured
• AWS CDK CLI for infrastructure deployment (includes Lambda)
• Amazon RDS PostgreSQL (deployed via CDK) - Setup Guide
• Plaid account (for financial institution integration)
• Stripe account (for payment processing)

Getting Started

For detailed setup instructions, see the Setup Guide.

Quick Start

1. Install dependencies:

   npm install

2. Set up environment variables:

   # Windows
   .\scripts\setup.ps1
   
   # Linux/Mac
   ./scripts/setup.sh

3. Deploy AWS Infrastructure (CDK):

   npm run cdk:install
   cd infrastructure/cdk
   cdk bootstrap aws://YOUR_ACCOUNT_ID/eu-central-1
   npm run deploy:dev

   This creates RDS database, Lambda API, API Gateway, S3 bucket, and CloudFront distribution. See CDK Quick Start for details.

4. Run migrations:

   npm run migrate:up

5. Start development servers:

   # Backend (local development)
   npm run dev:backend
   
   # Frontend (local development)
   npm run dev:frontend

6. Access your application:

   • API: Use the API Gateway URL from CDK output
   • Frontend: Use the CloudFront URL from CDK output
   • Local: http://localhost:3000 (frontend), http://localhost:3001 (backend)

Documentation

• 📖 Setup Guide - Complete setup instructions
• 🚀 CDK Quick Start - Deploy infrastructure in 5 minutes
• 🗄️ AWS RDS Setup - Detailed RDS configuration
• 🚢 Deployment Guide - Serverless production deployment
• 🔄 GitHub Actions Setup - CI/CD with OIDC authentication
• 📋 Quick Reference - Common commands and tips
• 🔧 AWS OIDC Setup - GitHub OIDC provider configuration

Architecture

Backend (packages/backend)

Serverless Express.js API deployed as AWS Lambda with API Gateway via CDK:

• Runtime: Node.js 20 on AWS Lambda
• API Gateway: RESTful API with CORS support
• Database: PostgreSQL with connection pooling (Amazon RDS)
• Encryption: AES-256-GCM for sensitive data
• Authentication: JWT-based authentication
• Integrations: Plaid API (financial data), Stripe API (payments)
• Migrations: node-pg-migrate for database schema management
• Deployment: AWS CDK (bundled automatically)

Key directories:

• src/config/: Configuration files (database, encryption, Plaid, Stripe)
• src/middleware/: Authentication and rate limiting
• src/utils/: Error handling utilities
• src/lambda.ts: Lambda handler using serverless-http
• migrations/: Database migration files

Frontend (packages/frontend)

Static React application hosted on S3 with CloudFront CDN:

• Hosting: AWS S3 static website hosting
• CDN: AWS CloudFront for global distribution
• Build Tool: Vite
• Routing: React Router (SPA routing via CloudFront)
• State Management: Zustand
• UI: Custom components with Lucide icons
• Testing: Vitest + React Testing Library
• Deployment: Automated via GitHub Actions

Infrastructure

AWS CDK manages all infrastructure in a single stack:

• Amazon RDS PostgreSQL: Managed database with automated backups
• AWS Lambda: Serverless API runtime with automatic bundling
• API Gateway: RESTful API endpoint with CORS
• S3 Bucket: Frontend hosting with proper bucket policies
• CloudFront Distribution: Global CDN with HTTPS and SPA support
• AWS Secrets Manager: Database credentials management
• Security Groups: Network access control for RDS and Lambda
• IAM Roles: Proper permissions for Lambda execution

Shared (packages/shared)

TypeScript types and Zod schemas shared between frontend and backend:

• Data models (Transaction, RecurringCharge, MoneyLeak, User)
• API request/response types
• Runtime validation schemas

Security Features

Data Encryption

• All sensitive data encrypted at rest using AES-256-GCM
• Per-user encryption keys derived from master key + user ID
• Plaid access tokens stored encrypted in database
• Master encryption key managed via AWS KMS

Transport Security

• TLS 1.3 enforced for all API communications
• Helmet.js for security headers
• CORS configured for frontend origin only

Authentication

• JWT-based authentication
• Bcrypt password hashing
• Rate limiting on API endpoints

Database Schema

The database includes the following tables:

• users: User accounts with tier and subscription information
• plaid_accounts: Connected financial institution accounts
• transactions: Financial transactions from Plaid
• recurring_charges: Detected recurring subscription charges
• money_leaks: Aggregated money leaks (recurring + micro-charges)

See packages/backend/migrations/001_initial_schema.sql for the complete schema.

Testing

Run tests for all packages:

npm test

Run tests for a specific package:

npm test --workspace=@silent-spend/backend
npm test --workspace=@silent-spend/frontend

Database Migrations

Create a new migration:

npm run migrate:create -- migration_name

Run pending migrations:

npm run migrate:up

Rollback last migration:

npm run migrate:down

Deployment

CI/CD with GitHub Actions

The project includes complete CI/CD workflows using GitHub OIDC authentication:

# Set up GitHub secrets (one time)
.\scripts\setup-github-secrets.ps1  # Windows
./scripts/setup-github-secrets.sh   # Linux/Mac

Automated Deployments:

• Development: Push to develop branch → Deploy to dev environment
• Production: Push to main branch → Deploy to production environment

What gets deployed:

1. Infrastructure (CDK): RDS database, Lambda function, API Gateway, S3 bucket, CloudFront distribution
2. Frontend: React app built and deployed to S3, CloudFront cache invalidated

See GitHub Actions Setup Guide for detailed configuration.

Manual Deployment

Deploy Everything (Infrastructure + API + Frontend):

cd infrastructure/cdk
npm run deploy:prod  # or deploy:dev

Deploy Frontend Only:

cd packages/frontend
npm run build
aws s3 sync dist/ s3://your-bucket-name --delete
aws cloudfront create-invalidation --distribution-id YOUR_ID --paths "/*"

Update Lambda Function Code:

# Redeploy CDK stack to update Lambda
cd infrastructure/cdk
npm run deploy:prod

Environment Configuration

Development

• Uses Plaid Sandbox environment
• Uses Stripe test mode
• Local development server or deployed Lambda
• S3 + CloudFront for frontend testing
• Detailed error messages enabled

Production

• Requires production Plaid credentials
• Requires production Stripe credentials
• AWS Lambda + API Gateway for serverless scaling
• S3 + CloudFront for global frontend distribution
• Database SSL enabled
• Error details hidden from API responses
• AWS KMS for encryption key management

API Documentation

API endpoints will be documented as they are implemented. The main endpoint groups are:

• /api/auth: Authentication and user management
• /api/plaid: Plaid Link integration and account connection
• /api/insights: Money leak insights and pattern detection
• /api/billing: Stripe subscription management
• /api/accounts: Connected account management

API Base URL: Provided by API Gateway after Lambda deployment

• Development: https://api-id.execute-api.eu-central-1.amazonaws.com/Prod/
• Production: https://api-id.execute-api.eu-central-1.amazonaws.com/Prod/

License

Proprietary - All rights reserved

Support

For questions or issues, please contact the development team.