Skip to content

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Macumba is a full-stack AI-powered travel planning application consisting of: - Backend: FastAPI service with PostgreSQL database and PostgreSQL-based cache - Frontend: Vue.js 3 application with Tailwind CSS - Infrastructure: Terraform configurations for AWS and GCP deployments

Common Development Commands

Backend (FastAPI) - Containerized Development

cd fastapi-backend

# Setup
cp .env.example .env  # Configure your environment variables

# Development with Docker (REQUIRED - no local Python environment)
docker-compose up -d  # Start all services (backend, PostgreSQL)
docker-compose logs -f backend  # View backend logs

# Execute commands inside containers
docker-compose exec backend alembic upgrade head           # Run database migrations
docker-compose exec backend python scripts/setup_db.py    # Initialize database with seed data

# Testing inside container
docker-compose exec backend pytest                                    # Run all tests
docker-compose exec backend pytest tests/api/test_recommendations.py # Run specific test file
docker-compose exec backend pytest --cov=app tests/                  # Run with coverage

# Debug configuration inside container
docker-compose exec backend python -c "from app.core.config import settings; print('AI_PROVIDER:', settings.AI_PROVIDER)"

Frontend (Vue.js)

cd frontend

# Setup
npm install

# Development
npm run dev  # Start dev server (uses localhost:8000 backend)

# Building for different environments
npm run build:dev      # Development deployment
npm run build:prod     # Production deployment

# Deployment to Firebase
npm run deploy:dev      # Deploy to development
npm run deploy:prod     # Deploy to production

High-Level Architecture

Backend Architecture

  • API Layer: FastAPI with dependency injection pattern
  • Routes organized in app/api/v1/endpoints/
  • Dependencies defined in app/api/deps.py and app/api/deps_services.py

  • API versioning via /api/v1 prefix

  • Service Layer: Business logic with AI integration

  • AI services with provider abstraction (app/services/ai/)
  • Primary/fallback AI strategy (Claude → Gemini)
  • External API integrations (Amadeus, Google Maps, TripAdvisor, Booking.com)
  • Multi-level caching with PostgreSQL-based cache (saves ~$110/month vs Redis)

  • Unified travel service for comprehensive booking data

  • Data Layer: SQLAlchemy ORM with Alembic migrations

  • Models in app/models/ with proper relationships
  • Pydantic schemas in app/schemas/ for API validation
  • JSONB storage for complex travel data structures
  • PostgreSQL cache_entries table for cost-effective caching

Frontend Architecture

  • Vue.js 3.5.13: Composition API with hybrid Pinia/legacy state management
  • Build System: Vite 6.2.0 with optimized development workflow
  • Environment-aware: Different API endpoints per deployment target
  • Component Structure: 40+ components organized by feature (auth, budget, destinations, etc.)
  • Maps Integration: Google Maps with custom markers and popups
  • Modern Features: Budget estimator, trip finder modal, toast notifications

Key Application Flow

  1. Initial Recommendations: Budget-first AI recommendations (rate-limited for anonymous users)
  2. Enriched Details: Detailed destination info with external API data (requires authentication)
  3. Trip Saving: Authenticated users can save and organize trips
  4. Budget Estimation: AI-powered comprehensive budget planning with exchange rates
  5. Activities & Attractions: Real-time activity recommendations via Booking.com
  6. Airport Mapping: Database-driven location-to-airport mapping system

Code Conventions

Backend

  • Use async/await for I/O operations
  • Type hints required for all functions
  • Services use dependency injection pattern
  • Cache expensive operations with @cached decorator
  • Error handling via typed exceptions in app.services.exceptions
  • Import order: standard library → third-party → local modules

Frontend

  • Vue 3 Composition API preferred over Options API
  • Components use PascalCase naming
  • Hybrid state management: Pinia for new features, legacy stores during migration
  • Tailwind CSS 3.3.3 for styling with consistent design system
  • @vueuse/core for Vue composition utilities

Key Development Patterns

Backend Service Pattern

# Services are injected via FastAPI dependencies
class RecommendationService:
    def __init__(self, ai_service: AIService, cache: CacheInterface):
        self.ai_service = ai_service
        self.cache = cache

    @cached(ttl=3600)
    async def get_recommendations(self, request: RecommendationRequest) -> List[Destination]:
        # Business logic here

AI Provider Abstraction

  • Base AI provider interface in app/services/ai/base.py
  • Concrete providers in app/services/ai/providers/
  • Automatic failover from Claude to Gemini
  • Health monitoring and circuit breaker pattern

Caching Strategy

  • AI responses cached in PostgreSQL to reduce API costs (saves ~$110/month vs Redis)
  • External API data cached for performance
  • Cache keys generated from request parameters
  • Cached responses don't count against rate limits
  • Fault-tolerant design - cache failures don't break application

Cost Optimization Strategy

  • PostgreSQL Cache: Replaces Redis/ElastiCache saving ~$110/month
  • S3 Lifecycle Policies: Intelligent tiering and automated archiving
  • Multi-Cloud Cost Monitoring: Comprehensive cost tracking across AWS and GCP
  • Resource Right-Sizing: Environment-specific resource allocation

Database Patterns

Models and Relationships

# Models use SQLAlchemy declarative base
class SavedTrip(Base):
    __tablename__ = "saved_trips"

    # JSONB storage for complex travel data
    recommendations = Column(JSONB)
    enriched_data = Column(JSONB)

    # Proper relationships
    user = relationship("User", back_populates="saved_trips")

Migration Workflow

  1. Modify models in app/models/
  2. Generate migration: alembic revision -m "description"
  3. Review and edit generated migration script
  4. Apply: alembic upgrade head

New Models and Features

  • Airport Mappings: Database-driven location-to-airport mapping (app/models/airport_mappings.py)
  • IATA Codes: Comprehensive airport code management (app/models/iata_codes.py)
  • Cache Metadata: PostgreSQL cache support with TTL and pattern matching
  • Enhanced User Profiles: Bio, profile pictures, email verification, password reset

Environment Configuration

Backend Environment Variables

Key variables defined in app/core/config.py: - AI_PROVIDER: Primary AI service (CLAUDE/GEMINI) - DATABASE_URL: PostgreSQL connection string - CACHE_TYPE: Cache backend type (postgres, file, redis) - defaults to postgres - ANTHROPIC_API_KEY, GOOGLE_AI_API_KEY: AI service keys - AMADEUS_API_KEY/SECRET: Flight data API - GOOGLE_MAPS_API_KEY: Maps integration - BOOKING_API_KEY: Booking.com integration for activities and hotels - SENDGRID_API_KEY: Email service integration

Frontend Environment Switching

  • .env.development.local: Local development (localhost:8000)
  • .env.development: Dev deployment (api-dev.macumbatravel.com)
  • .env.production: Production (api.macumbatravel.com)

Testing Strategy

Backend Testing

  • Unit tests for services with mocked dependencies
  • Integration tests for API endpoints
  • Performance tests in tests/performance/
  • Security tests in tests/security/
  • E2E tests in tests/e2e/
  • HTTP request files in tests/http_requests/ for manual testing
  • Test database isolation with fixtures

Test Organization

  • tests/api/: API endpoint tests
  • tests/services/: Business logic tests
  • tests/integration/: Cross-service integration tests
  • tests/e2e/: End-to-end user journey tests

Deployment Architecture

AWS Deployment (ECS)

  • Terraform infrastructure in infra/terraform_aws/
  • GitHub Actions OIDC for secure deployments
  • ECS with auto-scaling and load balancing
  • RDS PostgreSQL (also used for cost-effective caching)
  • AWS Bedrock integration for AI model access
  • S3 cost optimization with intelligent tiering and lifecycle policies

GCP Deployment (Cloud Run)

  • Terraform infrastructure in infra/terraform_gcp/
  • Cloud Run with automatic scaling
  • Cloud SQL PostgreSQL (also used for cost-effective caching)
  • Secret Manager for sensitive configuration
  • Enhanced monitoring with Cloud Monitoring and logging

Key Files to Understand

  • fastapi-backend/app/main.py: Application entry point and middleware setup
  • fastapi-backend/app/api/v1/api.py: API router configuration
  • fastapi-backend/app/services/recommendations.py: Core recommendation logic
  • fastapi-backend/app/services/ai/service.py: AI service orchestration
  • fastapi-backend/app/services/cache/postgres_cache.py: PostgreSQL-based caching system
  • fastapi-backend/app/services/external/booking/unified_service.py: Booking.com integration
  • fastapi-backend/app/api/v1/endpoints/budget.py: Budget estimation API
  • fastapi-backend/app/api/v1/endpoints/activities.py: Activities and attractions API
  • frontend/src/services/api.js: Frontend API client with environment switching
  • frontend/src/stores/: Pinia state management stores
  • frontend/src/components/BudgetEstimator.vue: Budget planning component
  • frontend/src/components/TripFinderModal.vue: Enhanced search interface

Rate Limiting System

  • Anonymous users: Limited initial recommendations per day
  • Authenticated users: Unlimited access to all features
  • Cached responses don't count against limits
  • Rate limit headers included in API responses

New API Endpoints and Services

Budget Estimation API

  • Endpoint: /api/v1/budget/estimate
  • Features: AI-powered budget calculation with seasonal pricing, exchange rates, and holiday preferences
  • Integration: Comprehensive cost analysis across all travel components

Activities & Attractions API

  • Endpoint: /api/v1/activities/
  • Features: Real-time activity recommendations via Booking.com integration
  • Filtering: Category, price range, ratings, and location-based filtering

Unified Travel Service

  • Service: app/services/external/booking/unified_service.py
  • Features: Single service for hotels, flights, attractions, and taxi bookings
  • Integration: Booking.com API for comprehensive travel data

Enhanced Authentication

  • Features: Extended user profiles with bio, profile pictures
  • Email Services: SendGrid integration for verification and password reset
  • Security: Enhanced password reset flow with email verification

Infrastructure Improvements

Multi-Cloud Cost Optimization

  • AWS: S3 intelligent tiering, lifecycle policies, Bedrock integration
  • GCP: Enhanced monitoring, Cloud SQL optimization, Secret Manager
  • Redis Replacement: PostgreSQL-based caching across both platforms
  • GitHub Actions: OIDC authentication for secure deployments

Monitoring and Observability

  • Performance Testing: Comprehensive load and API performance testing
  • Security Testing: Automated security testing pipeline
  • Health Checks: Service health monitoring with circuit breaker patterns
  • Logging: Structured logging with CloudWatch and Cloud Monitoring