backend-server-startup

name	backend-server-startup
description	Start the Budget Buddy FastAPI backend server on port 8000 with automatic CORS validation and error detection. Use when starting the backend, fixing server startup issues, debugging connection problems, or when the user asks to run/start the backend.
allowed-tools	["Bash(python*)","Bash(pkill:*)","Bash(lsof:*)","Bash(ps:*)","Read","Grep"]

Backend Server Startup

Overview

This skill helps you start the Budget Buddy FastAPI backend server correctly with automatic validation of CORS configuration, API paths, and common startup issues. It prevents the most frequent errors documented in the project's development guide.

Prerequisites

• Python 3.9+ installed
• Virtual environment created at .venv/
• Backend dependencies installed
• Working directory: /Users/franklindickinson/Projects/budget-buddy-2 (project root)

Quick Start

1. Verify Working Directory

CRITICAL: The backend MUST be started from the project root, not from the /backend directory.

pwd
# Should show: /Users/franklindickinson/Projects/budget-buddy-2

If in wrong directory:

cd /Users/franklindickinson/Projects/budget-buddy-2

2. Check Port Availability

lsof -i :8000

If port 8000 is in use, kill the existing process:

pkill -f "uvicorn.*8000"

3. Start the Backend

python -m uvicorn backend.api.main:app --reload --port 8000

Alternative (using server.py entry point):

python backend/server.py

4. Verify Startup Success

Look for these lines in the output:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process
INFO:     Started server process
INFO:     Application startup complete.

Test with curl:

curl -i http://127.0.0.1:8000/api/v2/transactions

Should return HTTP 200 or data (not 405 or CORS error).

Key Validation Points

1. CORS Configuration (CRITICAL)

The backend MUST have CORS middleware configured for local development. Check /backend/api/main.py:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000", "http://127.0.0.1:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Signs CORS is Missing:

• Frontend shows "Failed to fetch" errors
• Backend logs show 405 Method Not Allowed for OPTIONS requests
• Browser console shows CORS policy errors
• No data loads in frontend

2. API Path Configuration

The base_path in /backend/api/main.py must be:

base_path = "/api/v2"

Frontend expects: http://127.0.0.1:8000/api/v2/...

3. Module Import Paths

When running from project root, Python can find modules with backend. prefix:

from backend.database.session import get_session
from backend.services.database_service import DatabaseService

Common Issues & Solutions

Issue: "ModuleNotFoundError: No module named 'backend'"

Cause: Running uvicorn from /backend directory instead of project root

Solution:

cd /Users/franklindickinson/Projects/budget-buddy-2
python -m uvicorn backend.api.main:app --reload --port 8000

Issue: "Address already in use"

Cause: Another process is using port 8000

Solution:

# Find process
lsof -i :8000

# Kill it
pkill -f "uvicorn.*8000"

# Or kill by PID
kill -9 <PID>

Issue: Frontend can't load transactions

Checklist:

1. ✅ Backend running on port 8000?
2. ✅ CORS middleware configured?
3. ✅ base_path = "/api/v2"?
4. ✅ Frontend API config: http://127.0.0.1:8000/api/v2?
5. ✅ Database file exists at project root?

Issue: "Failed to fetch" or network errors

Solution:

1. Check CORS configuration in /backend/api/main.py
2. Verify backend logs for OPTIONS requests (should return 200, not 405)
3. Check browser console for specific CORS error messages
4. Ensure frontend is calling correct API base URL

Technical Details

Entry Points

Budget Buddy has two backend entry points:

1. backend/api/main.py (API v2)

   • Contains all routers
   • Requires base_path = "/api/v2"
   • Used for development with: python -m uvicorn backend.api.main:app --reload --port 8000

2. backend/server.py (Primary)

   • Mounts API app at /api
   • Handles database initialization
   • Used with: python backend/server.py

Database Initialization

Database auto-initializes on startup via startup_event() in server.py:

• Creates SQLite database at project root: budget_buddy.db
• Runs any pending migrations
• Initializes all tables from SQLAlchemy models

API Routes

26 routers under /api/v2/:

• /transactions - Transaction CRUD
• /budgets - Budget management
• /budget-categories - Category definitions
• /income - Monthly income tracking
• /ml - Machine learning classification
• /unified-classification - Combined classification
• /plaid - Bank integration
• /accounts - Account management
• /diagnostics - Health checks
• /sinking-funds - Sinking fund management
• /month-end-review - Monthly reflections
• /weekly-check-in - Weekly reviews
• /weekly-plans - Weekly planning
• /merchant-analytics - Merchant insights
• /buddy - AI insights (Buddy AI)
• Plus: trip-tags, goals, reflections, etc.

Testing the Skill

1. Kill any existing backend process

   pkill -f "uvicorn.*8000"
   

2. Start backend using this skill's instructions

   cd /Users/franklindickinson/Projects/budget-buddy-2
   python -m uvicorn backend.api.main:app --reload --port 8000
   

3. Verify success

   curl http://127.0.0.1:8000/api/v2/transactions
   

4. Check CORS

   curl -i -X OPTIONS http://127.0.0.1:8000/api/v2/transactions \
     -H "Origin: http://localhost:3000" \
     -H "Access-Control-Request-Method: GET"
   

   Should return headers including:

   access-control-allow-origin: http://localhost:3000
   access-control-allow-methods: *
   

Integration with Other Skills

• Full-Stack Setup - Creates the initial environment
• Development Diagnostics - Validates backend is running correctly
• Testing & Validation Suite - Requires backend running for API tests

References

• /backend/api/main.py:1-167 - CORS config, base_path, routers
• /backend/server.py:1-162 - Main server entry point
• /backend/database/session.py:1-89 - Database initialization
• CLAUDE.md - Complete development guidelines
• restart_all.sh - Reference startup script

Last Updated

January 1, 2026