AI-powered educational pathfinding platform with multi-agent architecture. EduRoad helps users achieve their career and educational goals through intelligent reverse pathfinding, real-time research, and dynamic pathway generation.
User states a goal → AI researches requirements → AI analyzes user's current state → AI calculates probability of success → AI generates personalized, actionable pathway → AI dynamically updates pathway based on progress
EduRoad uses a microservices architecture with multiple AI agents communicating via AWS EventBridge:
┌─────────────────────────────────────────────────────────────────┐
│ API Gateway │
│ (Rate Limiting, Auth, Routing) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Orchestrator Service │
│ (Claude Opus 4) │
│ Master Coordinator - Routes & Synthesizes │
└─────────────────────────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Research Agent │ │ Planning Agent │ │ Analysis Agent │
│ (Perplexity) │ │ (Claude Opus 4) │ │ (GPT-4 Turbo) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────┼───────────────────┘
▼
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Coaching Agent │ │ Matching Agent │ │Monitoring Agent │
│(Claude Sonnet 4)│ │ (Gemini Pro) │ │ (Phi-3 SLM) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
- Backend: Python 3.11+, FastAPI
- Database: PostgreSQL 15 (with JSONB for flexible schemas)
- Cache: Redis 7
- Message Bus: AWS EventBridge + SQS
- Container Orchestration: Kubernetes (EKS)
- Infrastructure: Terraform
- AI Models: Claude Opus 4, Claude Sonnet 4, GPT-4 Turbo, Perplexity API, Phi-3
- Frontend: Next.js, React, TypeScript
- Observability: CloudWatch, X-Ray, Sentry
eduroad-platform/
├── infrastructure/ # Terraform & Kubernetes configs
│ ├── terraform/
│ │ ├── modules/ # Reusable Terraform modules
│ │ └── environments/ # Dev, Staging, Prod configs
│ ├── kubernetes/
│ │ ├── base/ # Base K8s manifests
│ │ └── overlays/ # Environment-specific overlays
│ └── docker/ # Dockerfiles
├── services/ # Microservices
│ ├── api-gateway/
│ ├── orchestrator-service/
│ ├── research-service/
│ ├── planning-service/
│ ├── analysis-service/
│ ├── coaching-service/
│ ├── monitoring-service/
│ ├── matching-service/
│ ├── auth-service/
│ └── notification-service/
├── shared/ # Shared Python packages
│ ├── models/ # Pydantic models
│ ├── database/ # SQLAlchemy & repositories
│ ├── messaging/ # EventBridge client
│ ├── ai_clients/ # LLM API wrappers
│ ├── cache/ # Redis utilities
│ └── observability/ # Logging, metrics, tracing
├── frontend/ # Next.js web application
│ └── web-app/
├── scripts/ # Utility scripts
│ ├── migrations/ # Alembic migrations
│ ├── seed/ # Database seeding
│ └── deploy/ # Deployment scripts
└── tests/ # Test suites
├── unit/
├── integration/
└── e2e/
- Python 3.11+
- Docker & Docker Compose
- Node.js 18+ (for frontend)
- AWS CLI (for deployment)
-
Clone the repository
git clone https://github.com/eduroad/eduroad-platform.git cd eduroad-platform -
Set up environment
cp .env.example .env # Edit .env with your API keys and configuration -
Start infrastructure services
docker-compose -f docker-compose.dev.yml up -d postgres redis localstack
-
Install Python dependencies
python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install -e ".[dev]"
-
Run database migrations
alembic upgrade head
-
Start services
# Start all services docker-compose -f docker-compose.dev.yml up # Or start individual services for development uvicorn services.orchestrator-service.app.main:app --reload --port 8001
-
Start frontend (in a new terminal)
cd frontend/web-app npm install npm run dev
# All tests
pytest
# Unit tests only
pytest tests/unit -v
# Integration tests
pytest tests/integration -v
# With coverage
pytest --cov=shared --cov=services --cov-report=html# Format code
black .
isort .
# Lint
ruff check .
# Type check
mypy shared servicesOnce services are running, access the API documentation at:
- Orchestrator API: http://localhost:8001/docs
- Auth API: http://localhost:8008/docs
Agents communicate via AWS EventBridge with the following message format:
{
"sender": "orchestrator",
"receiver": "research",
"message_type": "request", # request, response, event, error
"payload": {
"action": "research_goal_requirements",
"goal_structured": {...}
},
"context": {
"user_id": "uuid",
"correlation_id": "uuid"
},
"correlation_id": "uuid",
"timestamp": 1704067200.0
}EduRoad includes built-in cost management:
- Caching: Research results cached in Redis (TTL: 1hr - 1 week)
- Model Selection: Smart model selection based on task complexity
- Batching: Non-urgent requests batched for efficiency
- Monitoring: Real-time cost tracking and budget alerts
Estimated cost per user: $0.50 - $2.00/month
-
Configure Terraform
cd infrastructure/terraform/environments/dev terraform init terraform plan terraform apply -
Deploy to EKS
kubectl apply -k infrastructure/kubernetes/overlays/dev
GitHub Actions workflows handle:
- CI: Lint, test, build Docker images
- CD: Deploy to EKS environments
See .env.example for all configuration options. Key variables:
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY |
Claude API key |
OPENAI_API_KEY |
OpenAI API key |
PERPLEXITY_API_KEY |
Perplexity API key |
DATABASE_URL |
PostgreSQL connection string |
REDIS_URL |
Redis connection string |
AWS_REGION |
AWS region for services |
MIT License - see LICENSE for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'feat: add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Documentation: https://docs.eduroad.ai
- Issues: https://github.com/eduroad/eduroad-platform/issues