Architecture Overview¶

System Architecture¶

Macumba Travel follows a modern, scalable architecture designed for high performance and cost efficiency.

graph TB
    User[👤 User] --> Frontend[🎨 Vue.js Frontend]
    Frontend --> LB[⚖️ Load Balancer]
    LB --> API[🔧 FastAPI Backend]
    API --> DB[(🗄️ PostgreSQL)]
    API --> Cache[(⚡ PostgreSQL Cache)]
    API --> AI[🤖 AI Services]
    AI --> Gemini[🧠 Gemini 2.0]
    AI --> Claude[🤖 Claude 3.5]
    API --> External[🌐 External APIs]
    External --> Amadeus[✈️ Amadeus]
    External --> Weather[🌤️ Weather API]
    External --> Maps[🗺️ Google Maps]

Core Components¶

1. Frontend (Vue.js 3)¶

• Framework: Vue.js 3 with Composition API
• Styling: Tailwind CSS for responsive design
• State Management: Pinia for predictable state
• Hosting: Firebase Hosting with CDN

2. Backend (FastAPI)¶

• Framework: FastAPI with async/await
• Database: PostgreSQL with SQLAlchemy ORM
• Cache: PostgreSQL-based cache (cost-optimized)
• AI Integration: Multi-provider with fallback

3. Infrastructure¶

• AWS: ECS deployment with Terraform
• GCP: Cloud Run deployment with Terraform
• CI/CD: GitHub Actions for automated deployment
• Monitoring: Built-in logging and health checks

Key Architectural Decisions¶

PostgreSQL Cache vs Redis¶

Decision: Use PostgreSQL for caching instead of Redis Rationale: - Cost savings: ~$110/month reduction - Simplified infrastructure: One database system - JSONB support: Rich data structure storage - TTL support: Built-in expiration handling

Two-Tier Recommendation System¶

Decision: Separate initial recommendations from enrichment Rationale: - Performance: 4.5s initial vs 15s+ enriched - User experience: Fast initial results - Cost optimization: Only enrich when requested

AI Provider Strategy¶

Decision: Gemini primary, Claude fallback Rationale: - Cost efficiency: Gemini more cost-effective - Performance: Both providers optimized for speed - Reliability: Automatic fallback prevents downtime

Data Flow¶

Recommendation Generation¶

1. User submits travel request
2. System checks PostgreSQL cache
3. If cache miss, AI service generates recommendations
4. Results stored in cache with TTL
5. Initial recommendations returned to user
6. Optional enrichment for detailed data

Enrichment Process¶

1. User selects recommendation for details
2. System retrieves cached recommendation
3. External APIs called for enrichment:
4. Flight pricing (Amadeus)
5. Weather data
6. Images and maps
7. Enriched data cached and returned

Scalability Patterns¶

Horizontal Scaling¶

• Stateless API: All services are stateless
• Load Balancing: Multiple backend instances
• Cache Layer: Reduces database load
• CDN: Global content delivery

Performance Optimization¶

• Async Processing: Non-blocking I/O operations
• Connection Pooling: Efficient database connections
• Caching Strategy: Multi-layer caching
• AI Prompt Optimization: Faster AI responses

Security Architecture¶

Authentication & Authorization¶

• JWT Tokens: Stateless authentication
• Rate Limiting: IP and user-based limits
• CORS: Proper cross-origin configuration
• Input Validation: Comprehensive request validation

Data Protection¶

• Encryption: Data encrypted in transit and at rest
• Secrets Management: Environment-based configuration
• Database Security: Connection encryption and access controls
• API Security: Rate limiting and input sanitization

Monitoring & Observability¶

Logging¶

• Structured Logging: JSON-formatted logs
• Request Tracking: Unique request IDs
• Error Tracking: Comprehensive error logging
• Performance Metrics: Response time tracking

Health Checks¶

• Database Health: Connection and query checks
• AI Service Health: Provider availability checks
• Cache Health: Cache connectivity verification
• External API Health: Dependency monitoring

Deployment Architecture¶

Development Environment¶

• Docker Compose: Local development setup
• Hot Reload: Fast development iteration
• Test Database: Isolated testing environment
• Mock Services: External API mocking

Production Environment¶

• Container Orchestration: ECS and Cloud Run
• Auto Scaling: Traffic-based scaling
• Blue-Green Deployment: Zero-downtime deployments
• Health Monitoring: Automated health checks

Future Architecture Considerations¶

Planned Enhancements¶

1. Microservices: Split into focused services
2. Event-Driven: Asynchronous event processing
3. Machine Learning: Personalization and optimization
4. Global CDN: Improved global performance
5. Real-time Updates: WebSocket integration

Scalability Roadmap¶

• Database Sharding: Horizontal database scaling
• Read Replicas: Improved read performance
• Distributed Caching: Global cache distribution
• Message Queues: Asynchronous task processing