Skip to content

maratron-ai/maratron-monorepo

BranchesTags

Repository files navigation

🏃‍♂️ Maratron - AI-Powered Running & Fitness Platform

Next.js TypeScript Python Docker PostgreSQL Redis

A comprehensive running and fitness platform with AI-powered coaching, social features, and high-performance caching. Built with modern containerized architecture for scalability and developer productivity.

🏗️ Architecture

Container Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web App       │    │   PostgreSQL    │    │      Redis      │
│   Container     │───▶│   Container     │    │    Container    │
│                 │    │                 │    │                 │
│ Next.js + AI    │    │ Primary DB      │    │ Cache Layer     │
│ Port: 3000      │    │ Port: 5432      │    │ Port: 6379      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        │                       │                       │
        └───────────────────────┼───────────────────────┘
                               │
                    ┌─────────────────┐
                    │  Docker Network │
                    │ (maratron_network)│
                    └─────────────────┘

Application Layer Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Maratron Platform                        │
├─────────────────────────────────────────────────────────────┤
│  Frontend (Next.js 15)    │  AI Server (Python + MCP)      │
│  ├─ React Components      │  ├─ Claude 3.5 Integration     │
│  ├─ TypeScript            │  ├─ User Context Management    │
│  ├─ Tailwind CSS          │  ├─ Smart Data Tools           │
│  └─ shadcn/ui             │  └─ Real-time Communication    │
├─────────────────────────────────────────────────────────────┤
│               Caching Layer (Redis 7)                      │
│  ├─ User Profile Caching (15min TTL)                       │
│  ├─ Runs Data Caching (5min TTL)                          │
│  ├─ Leaderboard Caching (10min TTL)                       │
│  └─ Social Feed Caching (3min TTL)                        │
├─────────────────────────────────────────────────────────────┤
│              Database Layer (PostgreSQL 15)                │
│  ├─ User Profiles & Preferences                           │
│  ├─ Running Activities & Metrics                          │
│  ├─ Social Graph & Interactions                           │
│  ├─ Training Plans & Goals                                │
│  └─ Gear Tracking & Analytics                             │
└─────────────────────────────────────────────────────────────┘

Project Structure

maratron-monorepo/
├── apps/
│   ├── web/                    # Next.js application
│   │   ├── src/
│   │   │   ├── app/           # App Router pages & API routes
│   │   │   ├── components/    # React components by feature
│   │   │   ├── lib/           # Core utilities & business logic
│   │   │   │   ├── cache/     # Redis caching system
│   │   │   │   ├── utils/     # Running calculations & helpers
│   │   │   │   ├── middleware/# Auth & rate limiting
│   │   │   │   └── mcp/       # AI server integration
│   │   │   ├── hooks/         # Custom React hooks
│   │   │   └── maratypes/     # TypeScript type definitions
│   │   ├── prisma/            # Database schema & migrations
│   │   └── public/            # Static assets
│   └── ai/                    # Python AI server
│       ├── src/maratron_ai/   # MCP server implementation
│       ├── tests/             # Python test suite
│       └── requirements/      # Python dependencies
├── docs/                      # Comprehensive documentation
├── assets/                    # Shared brand assets
├── docker-compose.yml         # Container orchestration
├── Dockerfile                 # Application container definition
└── package.json              # Workspace configuration

🚀 Quick Start

Prerequisites

  • Docker & Docker Compose - For containerized development
  • Node.js 20+ - For local development (optional)
  • Python 3.11+ - For AI server development (optional)

Development Setup

Option 1: Full Containerization (Industry Standard)

# Clone the repository
git clone <repository-url>
cd maratron-monorepo

# Start the complete development environment
npm run dev

# Access the application
open http://localhost:3000

Option 2: Hybrid Development (Fastest Performance)

# Start databases in containers, app locally (recommended for daily development)
npm run dev:hybrid

# Access the application
open http://localhost:3000

Option 3: Manual Setup (Advanced)

# Terminal 1: Start containerized databases
docker-compose up postgres redis -d

# Terminal 2: Start AI server locally
cd apps/ai && uv sync && python run_server.py

# Terminal 3: Start web application locally
cd apps/web && npm install && npm run dev

Available Commands

# Development
npm run dev              # Start complete development environment
npm test                 # Run test suite
npm run lint             # Code quality checks
npm run build            # Production build

# Database
npm run db:studio        # Open Prisma Studio
npm run db:seed          # Load comprehensive test data

# Maintenance
npm run clean            # Clean Docker environment

⚡ Performance Metrics

Redis Caching Performance

  • Cache Hit Rate: 85-95% for user data
  • Response Time: <2ms for cached responses
  • Database Load Reduction: 70-90%
  • Redis Operations: 2000+ ops/second
  • Cache Invalidation: Tag-based with smart patterns

Database Performance

  • Query Optimization: Comprehensive indexing on high-frequency patterns
  • Connection Pooling: Efficient resource utilization with health monitoring
  • N+1 Query Elimination: Transaction-based query optimization
  • Memory Usage: Pagination for large datasets

Application Performance

  • Build Time: <30 seconds with Turbopack
  • Live Reload: <500ms for code changes (hybrid mode: <100ms)
  • Bundle Size: Optimized with dynamic imports
  • Container Startup: ~5 seconds (hybrid), ~2-3 minutes (full Docker first time)

🏃‍♂️ Applications

Web Application (apps/web/)

  • Framework: Next.js 15 with App Router
  • Database: PostgreSQL with Prisma ORM
  • Auth: NextAuth.js
  • UI: Tailwind CSS + shadcn/ui
  • Features: Run tracking, social feeds, training plans, AI chat

AI Server (apps/ai/)

  • Framework: FastMCP (Model Context Protocol)
  • Database: Direct PostgreSQL with asyncpg
  • Features: User context management, intelligent responses, database tools
  • Package Manager: uv (modern Python package management)

📖 Complete Development Commands →

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

🗄️ Database & Caching

Containerized Infrastructure

  • PostgreSQL 15 - Primary database with persistent storage
  • Redis 7 - High-performance caching with AOF persistence
  • Automatic Schema Management - Prisma migrations applied on startup
  • Health Monitoring - Built-in health checks for all services
  • Data Persistence - Volumes ensure data survives container restarts

Redis Caching Strategy

// User data caching examples
cache.user.profile(userId, fetchUserFromDB, {
  ttl: 900, // 15 minutes
  tags: ['user', 'profile'],
  compress: true
});

cache.user.runs(userId, page, limit, fetchRunsFromDB, {
  ttl: 300, // 5 minutes  
  tags: ['user', 'runs'],
  serialize: true
});

cache.leaderboard(groupId, period, calculateRankings, {
  ttl: 600, // 10 minutes
  tags: ['leaderboard', 'social'],
  compress: true
});

📖 Database Operations →

🔧 Environment Variables

Containerized Development (Docker)

When using npm run dev, services automatically connect via Docker network:

# Automatically configured in Docker Compose
DATABASE_URL=postgresql://maratron:yourpassword@postgres:5432/maratrondb
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_ENABLED=true
REDIS_KEY_PREFIX=maratron:dev:

Hybrid Development (.env)

For npm run dev:hybrid (recommended for daily development):

# Database and Redis via localhost (Docker containers)
DATABASE_URL="postgresql://maratron:yourpassword@localhost:5432/maratrondb"
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your_secret_key

# Redis caching (containerized)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_ENABLED=true
REDIS_KEY_PREFIX=maratron:dev:

# AI API Keys
ANTHROPIC_API_KEY=your_anthropic_key
WEATHER__API_KEY=your_weather_key

Production Environment

# Production database (managed service)
DATABASE_URL="postgresql://user:pass@prod-db.cloud:5432/maratrondb"

# Production Redis (managed service)
REDIS_URL="redis://prod-redis.cloud:6379"
REDIS_ENABLED=true
REDIS_KEY_PREFIX=maratron:prod:

# Security
NEXTAUTH_SECRET=production-secret-key
NEXTAUTH_URL=https://your-domain.com

🧪 Testing

Current Status

  • ✅ Comprehensive test coverage - All tests passing across components
  • ✅ Redis caching validated - Real-world performance testing confirmed
  • ✅ MCP integration fully functional - AI chat responds with actual user data
  • ✅ Seed data available - Rich test data for validation and development
  • ✅ Docker integration tested - Full containerized stack validated

Web Application

cd apps/web
npm test              # Unit tests with Jest
npm run test:watch    # Watch mode for development
npm run lint          # ESLint validation
npm run build         # Production build validation

# Specific test categories
npm test -- --testPathPattern=cache      # Redis caching tests
npm test -- --testPathPattern=api        # API endpoint tests
npm test -- --testPathPattern=utils      # Utility function tests
npm test -- --testPathPattern=components # Component tests

AI Server

cd apps/ai
uv run pytest tests/unit/        # Unit tests
uv run pytest tests/integration/ # Integration tests
uv run pytest --cov=src         # With coverage

Seed Data for Testing

Load comprehensive test data for development and validation:

# Load seed data (from apps/web directory)
npm run db:seed

Includes:

  • 10 diverse users with different training levels (beginner to Olympic Trials)
  • 27 shoes across various brands and categories
  • 26 recent runs with comprehensive metrics
  • Complete social graph (posts, comments, likes, follows)
  • Training plans and group memberships

Test Accounts (password: "password"):

  • jackson@maratron.ai - Advanced runner, VDOT 60
  • john@example.com - Marathon enthusiast, VDOT 52
  • sarah@example.com - Track specialist, VDOT 58
  • Plus 7 more diverse running profiles

📚 Key Features

Running & Training

  • Run Tracking: Distance, pace, heart rate, elevation
  • Shoe Management: Mileage tracking and retirement alerts
  • Training Plans: AI-generated plans based on goals and VDOT
  • VDOT Calculations: Jack Daniels running calculator integration

Social Features

  • User Profiles: Customizable running profiles
  • Run Groups: Create and join running communities
  • Social Feed: Share runs and interact with other runners
  • Comments & Likes: Engage with the running community

AI Integration ⚡

  • Function Calling Architecture: 🔥 NEW - Claude 3.5 intelligently selects and uses 9 specialized tools
  • Automatic Context Management: Seamless user context setting - no technical details exposed
  • Real-Time Tool Execution: Claude accesses user data, analyzes patterns, and adds records on-demand
  • Intelligent Chat: Context-aware running advice with personalized data analysis
  • Multi-Tool Coordination: Complex queries automatically use multiple tools (runs + patterns + motivation)
  • Natural UX: Users simply ask questions - tools work transparently in background
  • MCP Protocol: Modern AI-to-application communication with comprehensive user context
  • Industry Best Practices: Professional implementation following enterprise AI assistant patterns

Available AI Tools: getUserRuns, listUserShoes, addRun, addShoe, analyzeUserPatterns, getMotivationalContext, getSmartUserContext, updateConversationIntelligence, getDatabaseSummary

📖 See Technical Implementation →

🔐 Security

  • Input validation and sanitization
  • Rate limiting on AI operations
  • Session management with timeouts
  • Environment-based configuration
  • No secrets in codebase

🤖 Claude Code Development Tools

SuperClaude was used as a pair coder. See flag usage here

When working with Claude Code, the following MCP tools are available for enhanced development:

🎨 Component Development

📚 Library Documentation

🌐 Browser Automation

  • Puppeteer MCP Server - Full browser automation
    • Documentation: Puppeteer API
    • Features: Navigate, screenshot, click, fill forms, evaluate JavaScript
    • Usage: Automated testing, screenshot generation, web scraping

🧠 Enhanced Thinking

  • Sequential Thinking - Multi-step problem-solving
    • Features: Reflection, revision, hypothesis generation and verification
    • Usage: Complex feature planning with iterative refinement

🔗 Additional Resources

Usage Examples

# Generate modern UI components
/ui create a responsive data table with filters

# Get up-to-date library documentation  
Ask about "react-hook-form validation patterns"

# Automate browser testing
Take a screenshot of the dashboard at localhost:3000

# Complex problem solving
Plan and implement a new feature with multiple iterations and refinements

# Search for brand assets
/logo Discord Slack GitHub

These tools significantly enhance development workflows by providing AI-powered component generation, real-time documentation access, browser automation, and sophisticated problem-solving capabilities.

📄 License

MIT License - see LICENSE file for details

About

A full-stack running and fitness web/mobile application with AI-powered features, social networking, and comprehensive training tools. This repo contains the Maratron MCP, Web and Mobile apps, and supporting DevOps codebases.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages