Ports & Services

Service Map

Service	Default Port	Bind Address	Protocol
PostgreSQL	5432	127.0.0.1 (default)	TCP
FastAPI / Uvicorn	8002	127.0.0.1	HTTP
React dev server (Vite)	5173	127.0.0.1	HTTP

---

PostgreSQL (Port 5432)

PostgreSQL is the sole persistent store for Mirabelle. Multiple databases coexist on the same PostgreSQL instance:

Database	Purpose
forecastai_master	Multi-tenancy master: master.accounts, master.superadmins, master.parameters
thebicycle	Tenant database — The Bicycle Company demo dataset
aerospace	Tenant database — MRO / aerospace demo dataset
postgres or thegreenery	Tenant database — additional demo tenant

pg_mooncake extension

The schema optionally uses pg_mooncake (a columnar extension) for demand_actuals, forecast_results, series_backtest_metrics, forecasts_by_origin, and fitted_distributions. If pg_mooncake is not installed, the schema creation silently skips the columnar wrapping and uses standard heap tables. No application behaviour changes.

Checking PostgreSQL

# Test connectivity
psql -h localhost -p 5432 -U postgres -c "SELECT version();"

# List all Mirabelle databases
psql -h localhost -p 5432 -U postgres -c "\l" | grep -E "thebicycle|aerospace|forecastai"

# Check active connections
psql -h localhost -p 5432 -U postgres -c "SELECT count(*) FROM pg_stat_activity WHERE state='active';"

Common Issues

Port 5432 in use by another PostgreSQL instance:

# Windows: find the PID
netstat -ano | findstr :5432

# Check which service owns it
Get-Process -Id <PID>

Connection refused (PostgreSQL not started):

# Windows Service
net start postgresql-x64-15   # adjust service name for your version

# Or via pg_ctl (adjust path)
"C:\Program Files\PostgreSQL\15\bin\pg_ctl.exe" start -D "C:\Program Files\PostgreSQL\15\data"

---

FastAPI / Uvicorn (Port 8002)

The API server runs at http://localhost:8002. All frontend API calls proxy through Vite to this port.

Endpoints Reference

• Swagger UI: http://localhost:8002/docs — interactive endpoint browser with JWT auth persistence.
• ReDoc: http://localhost:8002/redoc — alternative documentation view.
• OpenAPI JSON: http://localhost:8002/openapi.json — machine-readable schema.
• Version check: GET /api/version — returns the current API version string.

Starting the API

# Standard start (with reload for development)
cd files && python -m uvicorn api.main:app --host 127.0.0.1 --port 8002 --reload

# Background start (log to file — no --reload for WSL compatibility)
cd files && nohup python -m uvicorn api.main:app --host 127.0.0.1 --port 8002 --no-access-log > /path/to/api_8002.log 2>&1 &

# Windows background (via start.bat)
start.bat

Checking the API

# Basic health check
curl http://localhost:8002/

# Check API is responding with a 200
curl -o /dev/null -s -w "%{http_code}" http://localhost:8002/

Stopping Zombie Processes (Windows)

If the API process is stuck and port 8002 is occupied:

# Find all Python processes
tasklist | findstr python

# Kill all Python 3.13 processes (use carefully — kills all Python)
taskkill /F /IM python3.13.exe

# Kill by PID
taskkill /F /PID <PID>

Port Conflicts

If port 8002 is occupied, pick the next free port (8003, 8004, etc.) and update: 1. The Uvicorn launch command (--port 8003) 2. files/frontend/vite.config.js — the proxy target: 'http://localhost:8003' 3. The api_NNNN.log log file path

---

React Dev Server / Vite (Port 5173)

The React frontend runs at http://localhost:5173 in development mode. Vite proxies all requests starting with /api/ to http://localhost:8002.

Vite Proxy Configuration

Located in files/frontend/vite.config.js (or .ts):

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8002',
      changeOrigin: true,
    }
  }
}

This means http://localhost:5173/api/forecasts → http://localhost:8002/api/forecasts.

Starting the Frontend

# Development mode (hot-reload)
cd files/frontend && npm run dev

# Production build (creates files/frontend/dist/)
cd files/frontend && npm run build

Common Issues

Port 5173 already in use: Vite will automatically try the next port (5174, 5175, etc.) and print the actual URL it bound to in the terminal output.

API calls fail with CORS errors: CORS is configured in files/api/main.py to allow http://localhost:3000 and http://localhost:5173. If you run the frontend on a different port (e.g. 5174 after a port conflict), the CORS middleware will block the requests. Temporarily add your port to the allow_origins list in main.py.

Blank page in browser: Open browser DevTools (F12) → Console tab. Common causes: - API not running (Vite proxy returns 502) - JWT expired or missing from localStorage - JavaScript bundle error (run npm run build to see compile errors)

---

CORS Configuration

The FastAPI CORS middleware in files/api/main.py is configured as:

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

For production deployment behind a reverse proxy (e.g. Nginx), replace the localhost origins with your actual domain(s).

---

Service Start/Stop Summary (Windows)

Action	Command
Start everything	start.bat
Start API only	cd files && python -m uvicorn api.main:app --host 127.0.0.1 --port 8002 --reload
Start frontend only	cd files/frontend && npm run dev
Stop API (graceful)	Ctrl+C in the API terminal
Stop all Python processes	taskkill /F /IM python3.13.exe
Check port 8002	netstat -ano | findstr :8002
Check port 5173	netstat -ano | findstr :5173
Check port 5432	netstat -ano | findstr :5432