• Docker + Docker Compose
• Make (usually pre-installed on macOS/Linux)

# 1. Clone and configure backend env
cp backend/.env.example backend/.env
# Edit backend/.env with your Google OAuth credentials (see GCP Setup below)

# 2. Build and start all services
make docker-build
make docker-up

# 3. Run migrations and create a user
make docker-migrate
make docker-createsuperuser

# 4. View logs
make docker-logs

Open http://localhost:5174 and sign in with your superuser credentials.

make docker-down

make docker-shell

• Python 3.12+
• Node.js 20+
• uv — pip install uv
• pnpm — npm install -g pnpm
• Redis — brew install redis (macOS) or apt install redis (Linux)

cd backend

# Install dependencies
uv sync

# Copy and configure environment
cp .env.example .env   # edit with your Google OAuth credentials

# Run migrations and create a user
uv run python manage.py migrate
uv run python manage.py createsuperuser

# Start the API server (port 8000)
uv run python manage.py runbolt --dev

cd frontend

# Install dependencies
pnpm install

# Start dev server (port 5174)
pnpm dev

The arq worker processes the Gmail sync pipeline (fetch → classify → parse → materialize).

# Terminal 1: Start Redis
make redis

# Terminal 2: Start worker (auto-reloads on code changes)
make worker

make -j4 up

Open http://localhost:5174 and sign in with your superuser credentials.

Production mode uses:

• Caddy for the frontend (static build + API reverse proxy)
• Django Bolt with --processes 4, connection pooling via psycopg[pool]
• PostgreSQL with persistent volumes
• No hot-reload, no dev volume mounts

# 1. Configure backend/.env with production values:
#    - DEBUG=False
#    - ALLOWED_HOSTS=your-domain.com
#    - BOLT_JWT_SECRET=<strong random value, min 32 chars>
#    - SECRET_KEY=<strong random value>
#    - CORS_ALLOWED_ORIGINS=https://your-domain.com
#    - DATABASE_URL=postgresql://finnlens:finnlens@postgres:5432/finnlens (set automatically by compose)

# 2. Optional: override compose settings via environment
#    POSTGRES_PASSWORD=your-strong-password
#    FRONTEND_PORT=443
#    ALLOWED_HOSTS=your-domain.com,127.0.0.1
#    CORS_ALLOWED_ORIGINS=https://your-domain.com

# 3. Build and start
make docker-prod

# 4. Run migrations
docker compose -f docker-compose.yml -f docker-compose.prod.yml exec backend \
  uv run python manage.py migrate

# 5. Create superuser
docker compose -f docker-compose.yml -f docker-compose.prod.yml exec backend \
  uv run python manage.py createsuperuser

make docker-prod-down

Note: For automatic HTTPS, update the Caddyfile with your domain: replace :80 with your-domain.com.

Demo mode runs the frontend with zero backend dependency — all API calls are intercepted and return realistic mocked data (Indian financial data: INR, Indian banks, merchants).

cd frontend

# Dev server with demo mode
pnpm dev:demo

# Production demo build
pnpm build:demo

Open http://localhost:5174 — you'll see a marketing landing page instead of the login form. Click "Quick Login as Demo User" or enter demo / demo.

The marketing landing page is only enabled for pnpm dev:demo. pnpm build:demo still uses mocked data, but keeps the normal login page.

What works in demo mode:

• All pages display realistic mock data (overview, accounts, transactions, analytics, calendar, subscriptions, investments, budgets, assets, life events, waitlist, notifications, settings)
• Write operations (add account, update profile, manage subscriptions, manage sender rules) modify in-memory state
• Gmail sync simulates a real pipeline — click Sync and watch the 6-step pipeline progress in real time
• Category overrides on transactions persist in-memory
• A subtle "Demo Mode" banner appears at the top of the app

What is mocked:

• No real API calls are made — the backend is not required
• Login is local (demo:demo credentials, no JWT validation)
• Gmail OAuth flow returns mock responses

1. Go to Google Cloud Console
2. Click the project dropdown → New Project
3. Name it (e.g., FinnLens) and create

1. Navigate to APIs & Services → Library
2. Search and enable:
   • Gmail API (for email sync)

1. Navigate to APIs & Services → OAuth consent screen
2. Choose External user type
3. Fill in:
   • App name: FinnLens
   • User support email: your email
   • Developer contact email: your email
4. Under Scopes, add:
   • email
   • profile
   • https://www.googleapis.com/auth/gmail.readonly
5. Under Audience → Test users, add your email address so only you can access this
6. (Optional) Submit for verification to make it available to anyone

1. Navigate to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Web application
4. Name: FinnLens Web
5. Authorized JavaScript origins:
   • http://localhost:5174 (local dev)
   • http://localhost (Docker prod)
   • Your production domain (e.g., https://finnlens.com)
6. Authorized redirect URIs:
   • http://localhost:5174/oauth/google/callback (local dev)
   • http://localhost/oauth/google/callback (Docker prod)
   • https://your-domain.com/oauth/google/callback (production)
7. Click Create
8. Copy the Client ID and Client Secret

Add to backend/.env:

GOOGLE_CLIENT_ID=<your-client-id>
GOOGLE_CLIENT_SECRET=<your-client-secret>
GOOGLE_REDIRECT_URI=http://localhost:5174/oauth/google/callback
GMAIL_TOKEN_ENCRYPTION_KEY=<generate with command below>

Generate a Fernet encryption key for storing Gmail tokens securely:

uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

make docker-createsuperuser

cd backend
uv run python manage.py createsuperuser

Follow the prompts — email and password are all that's required.

Tip: If you get a database connection error, make sure PostgreSQL is running and DATABASE_URL is set correctly in backend/.env.

After signing in, you'll land on the Dashboard. You should see an empty state with no accounts or transactions.

1. Navigate to Settings → Gmail (or click the Gmail sync prompt)
2. Click Connect Google Account
3. Authorize the app when redirected to Google
4. You'll be redirected back — your Gmail account is now linked

1. Navigate to Accounts or click Sync in the sidebar
2. Click Sync Now
3. The 6-step pipeline runs automatically:
   • Fetch → Classify → Parse → Materialize → Classify Transactions → Detect Subscriptions
4. Wait for completion (first sync may take a few minutes depending on email volume)

• Dashboard — overview of spending, upcoming bills, net worth
• Accounts — credit cards and their balances
• Transactions — all extracted transactions with search and filters
• Analytics — spending by category, merchant, and time period
• Subscriptions — auto-detected recurring charges
• Investments — portfolio data from financial emails

• Category overrides — click any transaction to re-categorize it
• Sender rules — manage which email senders are processed for financial data
• Settings — update profile, manage Gmail connection, configure preferences