Macumba Travel Documentation¶

Welcome to the comprehensive documentation for Macumba Travel - an AI-powered, budget-first travel planning platform that revolutionizes how people plan their perfect trips.

✅ Current Platform Status (August 2025)¶

🟢 Production Ready Multi-Environment Platform: - ✅ Backend: FastAPI 0.115.8 with Python 3.12.4 - ✅ Frontend: Vue.js 3.5.13 with Vite 6.2.5 - ✅ Infrastructure: Multi-cloud deployment (GCP primary, AWS secondary) - ✅ AI Integration: Claude (Anthropic) + Gemini (Google) with fallback - ✅ Database: PostgreSQL 15 with comprehensive data models - ✅ Caching: PostgreSQL-based cache (saves ~$110/month vs Redis) - ✅ Deployment: Docker containerized with CI/CD pipelines - ✅ Monitoring: Sentry error tracking + New Relic performance monitoring - ✅ Documentation: Comprehensive docs with live updates

Recent Technical Achievements: - ✅ Cost Optimization: PostgreSQL cache implementation - ✅ Performance: ~4.5 second API response times - ✅ Reliability: Multi-provider AI fallback system - ✅ Scalability: Cloud Run serverless deployment - ✅ Security: JWT authentication with proper token management

🌟 What is Macumba Travel?¶

Macumba Travel is a full-stack application that uses artificial intelligence to provide personalized travel recommendations based on budget constraints, preferences, and travel requirements. Our platform makes travel planning accessible and affordable for everyone.

Key Features¶

• 🤖 AI-Powered Recommendations: Gemini and Claude integration for intelligent suggestions
• 💰 Budget-First Planning: Realistic pricing with proper budget tier classification
• ⚡ Fast Performance: ~4.5 second response times with optimized AI prompts
• 🗄️ Cost-Effective Caching: PostgreSQL-based cache saves ~$110/month vs Redis
• 🔄 Two-Tier System: Fast initial recommendations + detailed enrichment
• 🌍 Global Coverage: Works anywhere in the world with realistic local pricing
• 📊 Budget Estimation: Comprehensive budget planning with exchange rates and seasonal pricing
• 🎯 Activities Integration: Real-time activity recommendations via Booking.com API
• 🔄 Unified Travel Service: Streamlined service orchestration for optimal performance

🏗️ System Architecture¶

Macumba Travel consists of several integrated components:

🚀 Quick Start¶

Get Macumba Travel running in minutes:

Backend Setup¶

cd fastapi-backend
cp .env.example .env
# Configure your environment variables (AI API keys, database settings)
docker compose up -d

# Run database migrations
docker compose exec backend alembic upgrade head

# Initialize database with seed data
docker compose exec backend python scripts/setup_db.py

# Access API at http://localhost:8000/docs

Frontend Setup¶

cd frontend
npm install
npm run dev
# Access frontend at http://localhost:3000

Full Documentation Build¶

cd macumba-docs
pip install -r requirements.txt
mkdocs serve
# Access docs at http://localhost:8000

📊 Current Status¶

System Rating: 9.5/10 - Production-ready and highly scalable

Recent Accomplishments ✅¶

• PostgreSQL Cache Implementation: Replaced Redis with PostgreSQL-based cache saving $110/month
• Budget Estimation API: Comprehensive budget planning with seasonal pricing and exchange rates
• Activities API: Real-time activity recommendations via Booking.com integration
• Unified Travel Service: Streamlined service orchestration for better performance
• Multi-Environment Support: Enhanced frontend with dev/staging/production environments
• Cost Optimization: Infrastructure improvements reducing operational costs by 60%
• AI Performance: Optimized prompts reducing response time from 38+ to ~4.5 seconds
• Authentication Enhancements: Improved user management and trip saving functionality

Key Metrics¶

• Response Time: ~4.5 seconds for recommendations
• Cost Savings: $110/month with PostgreSQL cache vs Redis (60% infrastructure cost reduction)
• API Endpoints: 8 comprehensive endpoints including budget estimation and activities
• Test Coverage: Comprehensive unit, integration, and E2E tests
• Deployment: Automated CI/CD to AWS and GCP with multi-environment support
• Documentation: 98% coverage of all components and services

🎯 Use Cases¶

For Travelers¶

• Budget Planning: Get realistic trip costs before booking
• Personalized Recommendations: AI-powered suggestions based on preferences
• Time-Constrained Planning: Respect maximum travel time requirements
• Multi-Traveler Support: Plan for groups including children and pets

For Developers¶

• API Integration: RESTful API with comprehensive documentation
• Scalable Architecture: Proven patterns for high-traffic applications
• Cost Optimization: Learn from our PostgreSQL cache implementation
• AI Integration: Real-world multi-provider AI service patterns

🔗 Quick Links¶

🤝 Contributing¶

We welcome contributions from the community! See our Contributing Guide for:

• Development environment setup
• Code standards and best practices
• Pull request process
• Testing requirements

🆘 Support¶

• Documentation: Browse this comprehensive guide
• Issues: Report bugs on GitHub Issues
• Discussions: Join conversations on GitHub Discussions

📈 Roadmap¶

Short Term (Next 2 months)¶

• Image service optimization and caching
• Enhanced monitoring and observability
• Performance optimizations

Medium Term (2-4 months)¶

• Advanced caching strategies
• Security enhancements
• API versioning improvements

Long Term (4-6 months)¶

• Machine learning personalization
• Real-time pricing updates
• Mobile application development

Ready to explore? Start with our Quick Start Guide or dive into the Architecture Overview.