WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Development Commands

Quick Start Commands

# Start backend (FastAPI)
cd backend
python -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000

# Start frontend (Next.js) - separate terminal
cd frontend
npm run dev

Backend Development

# Install dependencies
cd backend
pip install -r requirements.txt

# Run with specific configuration
python -m uvicorn backend.main:app --reload --port 8000

# Run tests
pytest -v --cov=. --cov-report=html
pytest tests/test_health.py -v  # Single test file

# Type checking
mypy backend/ --config-file=mypy.ini

# Code formatting
black backend/
isort backend/

# Linting
flake8 backend/

Frontend Development

cd frontend

# Install dependencies
npm install

# Development server
npm run dev

# Build for production
npm run build

# Type checking
npm run typecheck

# Start production server
npm run start

Testing Commands

# Run all backend tests
cd backend && pytest tests/ -v

# Run frontend tests
cd frontend && npm test

# Run specific test scripts
python test_backend_health.py
python comprehensive_tester.py
python scripts/backend_smoke.py

Docker Commands

# Development with Docker Compose
docker-compose up -d

# Production deployment
export PRODUCTION=true
docker-compose -f docker-compose.yml up -d

# Stop services
docker-compose down

# View logs
docker-compose logs backend
docker-compose logs frontend

Database Commands

# Database status (works offline too)
curl http://127.0.0.1:8000/db/status

# Health check
curl http://127.0.0.1:8000/health

Architecture Overview

Technology Stack

Backend:

• Framework: FastAPI (Python 3.11+) with uvicorn
• Database: Supabase (PostgreSQL) with offline in-memory fallback
• Cache: Redis (optional)
• AI Services: OpenAI GPT-4, Google Gemini Pro
• Authentication: JWT tokens with Bearer authentication

Frontend:

• Framework: Next.js 14 with TypeScript
• Styling: Tailwind CSS + Material-UI
• State Management: React Context (AuthContext, OfflineContext)
• Charts: Chart.js with react-chartjs-2
• PWA: next-pwa with offline capabilities

Backend Architecture

The backend uses a modular router-based architecture with API versioning:

backend/
├── main.py              # FastAPI app with all routers
├── config.py            # Centralized configuration
├── routers/            # Feature-based API routes
│   ├── auth.py         # Authentication & user management  
│   ├── arbitration.py  # Multi-AI decision engine
│   ├── rag.py          # Retrieval-augmented generation
│   ├── transactions.py # Transaction CRUD operations
│   ├── multimodal.py   # Voice, image, text processing
│   └── [20+ other specialized routers]
├── utils/              # Shared utilities
└── inmemory_store.py   # Offline mode data storage

Key Architectural Patterns:

1. API Versioning: /v1/* and /v2/* endpoints for backward compatibility
2. Offline-First: Automatic fallback to in-memory store when Supabase unavailable
3. Multi-Provider AI: Arbitration engine supporting OpenAI + Google Gemini
4. Modular Routers: Each feature domain has its own router module
5. Dependency Injection: Reusable dependencies for auth, database, etc.

Frontend Architecture

Provider Hierarchy (wraps all pages):

_app.tsx
├── AuthProvider      # User authentication state
├── OfflineProvider   # Network status & sync queue  
├── ToastProvider     # Notifications system
└── AppLayout         # Navigation & status indicators

Key Frontend Patterns:

1. Context-Based State: Auth, offline sync, and toast notifications
2. Offline Queue: IndexedDB for storing operations when offline
3. Progressive Sync: Background synchronization when connection restored
4. API Client: Typed axios wrapper with error handling
5. Route Protection: Dashboard requires authentication

AI Intelligence Layer

The project features a sophisticated Multi-Agent Arbitration System:

• Parallel Execution: Runs OpenAI and Gemini models simultaneously
• Strategy Engine: first_success, heuristic_scoring, consensus, etc.
• Explainability: Provides rationale and confidence scores for decisions
• Safety Layer: Pre/post moderation with PII detection
• Feedback Loop: User rating system for continuous improvement

Authentication System

Token Types:

• expected-token → Maps to test user user123 (development)
• localsecret → Shared secret from .env file
• JWT tokens with configurable expiration

Auth Flow:

1. Frontend login → backend validates credentials
2. Backend issues JWT token
3. Frontend stores token and includes in API requests
4. Backend validates token via dependency injection

Offline Capabilities

Backend Offline Mode:

• Automatically enabled when SUPABASE_URL missing
• Uses thread-safe in-memory store
• Supports full auth and transaction CRUD
• Seeds demo data on startup

Frontend Offline Mode:

• Detects network status via navigator.onLine
• Queues operations in IndexedDB
• Syncs automatically when connection restored
• Shows offline indicators in UI

Development Workflow

Environment Setup

1. Copy .env.example to .env and configure
2. For offline development, omit SUPABASE_URL and SUPABASE_ANON_KEY
3. Backend auto-switches to in-memory mode when Supabase unavailable

Authentication Testing

# Test with shared secret
curl -H "Authorization: Bearer localsecret" http://127.0.0.1:8000/v1/profile

# Test with expected token
curl -H "Authorization: Bearer expected-token" http://127.0.0.1:8000/v1/profile

Adding New Features

1. Backend: Create router in backend/routers/, add to main.py
2. Frontend: Add component in components/, create page in pages/
3. API Client: Extend lib/api.ts with typed functions
4. Tests: Add tests for both backend and frontend

API Versioning Strategy

• v1: Stable API for core functionality
• v2: Enhanced features with backward compatibility
• v3: Future/experimental features

New features should start in v2/v3, then migrate to v1 once stable.

Common Troubleshooting

Port Conflicts

• Backend defaults to port 8000
• Frontend defaults to port 3000 (auto-selects 3001, 3002, etc.)
• Docker Compose uses same default ports

CORS Issues

• Development: Automatically includes localhost:3000-3010
• Production: Set ALLOWED_ORIGINS environment variable
• Debug endpoint: GET /debug/cors

Offline Mode Issues

• Missing SUPABASE_URL triggers offline mode
• Check /db/status endpoint to confirm mode
• In-memory data resets on restart (by design)

Authentication Errors

• Verify Authorization: Bearer <token> header format
• Check token validity (expected-token, localsecret, or valid JWT)
• /v1/profile endpoint requires authentication

Testing Strategy

Test Types

• Unit Tests: pytest for backend, jest for frontend
• Integration Tests: Full API workflow tests
• Smoke Tests: Basic connectivity and health checks
• Load Tests: locustfile.py for performance testing

Test Files Location

• Backend tests: backend/tests/
• Frontend tests: frontend/__tests__/
• Integration tests: Root level (test_*.py)
• Smoke tests: scripts/ directory

Running Tests in Different Modes

# Online tests (requires Supabase)
SUPABASE_URL=<url> pytest

# Offline tests (uses in-memory store)
pytest  # without SUPABASE_URL

# Specific test categories
pytest -m "not integration"  # Skip integration tests
pytest tests/test_health.py  # Single test file

This architecture provides a solid foundation for rapid development while maintaining production-readiness and scalability.