Tech Stack

A comprehensive overview of the technologies powering Finnance.

Overview

Finnance is built as a modular monorepo combining cross-platform mobile and web applications with a robust Python backend and real-time database.

mono/
├── frontend/
│   ├── apps/
│   │   ├── next/        # Next.js web application
│   │   ├── expo/        # Expo mobile application
│   │   ├── admin/       # Admin dashboard (Mantine)
│   │   └── docs/        # Documentation site
│   ├── packages/
│   │   ├── assets/      # Shared assets
│   │   ├── components/  # Shared UI components
│   │   │   ├── common/  # Cross-platform components
│   │   │   └── primitives/ # Base UI components
│   │   ├── modules/     # Feature-based modules
│   │   ├── hooks/       # Shared React hooks
│   │   ├── utils/       # Utility functions
│   │   └── config/      # Configuration files
│   └── package.json     # Workspace configuration
└── backend/
    ├── fast-api/        # Python FastAPI server
    ├── supabase/        # Database & Edge Functions
    └── express-js/      # Express.js (legacy)

Frontend Stack

Next.js Web Application

The primary web interface built with:

Next.js 14 with App Router
React 18 with Server Components
TypeScript for type safety
Tailwind CSS for styling
Framer Motion for animations

Expo Mobile Application

Cross-platform mobile app supporting iOS and Android:

Expo SDK 50+
React Native with Expo Router
GlueStack UI component library
Reanimated for smooth animations

Shared Packages

The monorepo shares code across platforms:

@app-launch-kit/components - UI components
@app-launch-kit/modules - Feature modules (auth, transactions, etc.)
@app-launch-kit/hooks - Custom React hooks
@app-launch-kit/utils - Utility functions

Backend Stack

FastAPI (Primary)

The main API server powering Finn's AI capabilities:

Python 3.11+
FastAPI for high-performance async APIs
OpenAI Agents SDK for AI orchestration
Supabase Python Client for database access
Pydantic for data validation

# Start the FastAPI server
uvicorn app.main:app --reload

Key API Features

Health check and monitoring
CORS enabled for cross-origin requests
Interactive Swagger UI at /docs
ReDoc documentation at /redoc

Database & Backend Services

Supabase

Primary database and real-time infrastructure:

PostgreSQL database
Row Level Security (RLS) for data protection
Real-time subscriptions
Edge Functions for serverless compute
Storage for file uploads
Auth for user authentication

# Start local Supabase
cd backend/supabase && supabase start

# Access dashboard at http://localhost:54323

Key Tables

households - User account groups
transactions - Financial transaction data
chat_session_turns - AI conversation history
intents - User financial goals and rules

AI & Machine Learning

OpenAI Integration

GPT-4o for natural language understanding
Agents SDK for multi-agent orchestration
Function calling for structured tool execution

Agent Architecture

The AI system uses a multi-agent pattern with:

Orchestrator agents that coordinate specialists
Tool functions for database operations
Context management for conversation state
Handoffs for agent-to-agent transitions

Infrastructure

Deployment

Component	Platform	URL
Web App	Vercel	finnance.ai
API Server	AWS ECS	api.finnance.ai
Database	Supabase Cloud	Project-specific
Mobile App	App Store / Play Store	-

AWS Services

ECR - Docker container registry
ECS - Container orchestration
Secrets Manager - Environment secrets
CloudWatch - Logging and monitoring

CI/CD

GitHub Actions workflows for:

Frontend deployment to Vercel
FastAPI deployment to AWS ECS
Supabase migrations
Edge Functions deployment

Development Tools

Package Management

Yarn Workspaces for monorepo management
pip / Poetry for Python dependencies

Code Quality

ESLint + Prettier for JavaScript/TypeScript
Black + Ruff for Python
TypeScript strict mode enabled

Testing

Jest for JavaScript unit tests
Pytest for Python tests
Cypress for E2E web testing
Detox for mobile E2E testing

Documentation

Storybook for component documentation
Swagger/OpenAPI for API documentation
MDX for content documentation

Quick Start Commands

# Install all dependencies
yarn install

# Start Supabase (in one terminal)
cd backend/supabase && supabase start

# Start FastAPI (in another terminal)
cd backend/fast-api && uvicorn app.main:app --reload

# Start Next.js web app (in another terminal)
yarn next:dev

# Start Expo mobile app (in another terminal)
yarn expo:start

Local URLs

Next.js App: http://localhost:3000
FastAPI Docs: http://localhost:8000/docs
Supabase Dashboard: http://localhost:54323

Environment Setup

Required Environment Variables

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# OpenAI
OPENAI_API_KEY=your-openai-key

# API
NEXT_PUBLIC_API_URL=https://api.finnance.ai

See the Setup Guide for detailed configuration instructions.