Architecture Overview

System Design

The Fellowship Exercises platform is a distributed system combining multiple services and components:

┌─────────────────────────────────────────────────────────┐
│         Agents (ReAct Pattern)                          │
└─────────────────────────────────────────────────────────┘
                          ↓
┌──────────────────────────────────────────────────────────┐
│  MCP Protocol (Standard Tool Communication)             │
└──────────────────────────────────────────────────────────┘
    ↓              ↓               ↓              ↓
┌──────────┐  ┌─────────┐  ┌─────────┐  ┌──────────────┐
│ Jenkins  │  │  Gitea  │  │ MailHog │  │ Custom Tools │
│  MCP <br/>Server │  │  MCP     │  │   (Test)    │  │                │
│          │  │ Server  │  │         │  │              │
└──────────┘  └─────────┘  └─────────┘  └──────────────┘
    ↓              ↓              ↓              ↓
┌──────────┐  ┌─────────┐  ┌─────────┐  ┌──────────────┐
│ Jenkins  │  │  Gitea  │  │ MailHog │  │ External     │
│ Service  │  │ Service │  │ Service │  │ Services     │
└──────────┘  └─────────┘  └─────────┘  └──────────────┘

Service Components

Agents

AI systems that:

• Reason about problems using LLMs
• Discover and use tools via MCP
• Iterate toward solutions
• Coordinate across multiple services

MCP Servers

Services that expose capabilities:

• Advertise available tools
• Receive tool requests from agents
• Execute operations on backend systems
• Return results to agents

Backend Services

Infrastructure that does the actual work:

• Jenkins: CI/CD automation
• Gitea: Code repositories
• MailHog: Email testing
• Custom services you create

Technology Stack

Component	Technology	Purpose
IDE	code-server	Browser-based development
Language	Python / TypeScript	Build agents and servers
Protocol	MCP	Agent-tool communication
LLM	Claude / GPT-4	Agent reasoning
CI/CD	Jenkins	Build automation
SCM	Gitea	Version control
Learning Path	Docusaurus	Documentation

Developer Environment

The learning environment includes:

• code-server (port 8080)

  • Browser-based IDE
  • Terminal access
  • Git integration

• Jenkins (port 8081)

  • CI/CD automation
  • Build pipeline management
  • Webhook support

• Gitea (port 3000)

  • Git repository hosting
  • User management
  • Webhook integration

• MailHog (port 1025, UI: 8025)

  • Email capture for testing
  • Message inspection

Key Architectural Patterns

1. ReAct Pattern (Agents)

Agent Reasoning Loop:
  Reason → Act → Observe → Repeat

Agents think about problems, use tools, observe results, and iterate.

2. MCP Protocol (Tool Communication)

Standard interface for tools:

Agent: "What tools do you have?"
Server: "I have: create_job, run_build, get_status"
Agent: "Run tool 'run_build' with params {job: 'test'}"
Server: "Result: build #42 started"

3. Multi-Server Orchestration (Complex Workflows)

Agents coordinate across multiple services:

Agent:
  1. Call Jenkins: trigger build
  2. Wait for completion
  3. Call Gitea: check commit
  4. Send email via MailHog

4. Event Sourcing (State Management)

State changes recorded as immutable events:

Event: "Build #42 started"
Event: "Test passed"
Event: "Artifact uploaded"
→ Current state: Build succeeded

Learning Progression

The five exercises teach these patterns in order:

Exercise	Concept	Service
1	ReAct agents	Local LLM
2	MCP servers	Jenkins
3	Agent orchestration	Jenkins + Custom
4	Advanced MCP servers	Gitea
5	Full system integration	All services

Data Flow Example

How an agent solves a problem:

1. User asks: "Check if my build passed"

2. Agent reasons:
   "I need to check Jenkins build status"

3. Agent discovers Jenkins MCP server
   "These tools available: run_build, get_status, ..."

4. Agent acts:
   Calls: get_status(job="my-job")

5. Agent observes:
   Result: {"status": "passed", "duration": "2m45s"}

6. Agent concludes:
   "Yes, your build passed in 2m45s"

7. Agent acts again (to be helpful):
   Calls: send_email(recipient="user@example.com", 
                     message="Your build passed!")

8. Outcome: User is notified, goal achieved

Deployment Architecture

Local Development

All services run on your EC2 instance using Docker Compose.

Production (Future)

• Agents: Deployed to serverless (AWS Lambda)
• MCP Servers: Deployed to containers (ECS)
• Services: Managed via CloudFormation
• Documentation: CDN (S3 + CloudFront)

Scalability Considerations

Current Design

• Single instance: All services on one EC2
• Suitable for: Learning, small teams (< 100 users)
• Limit: ~5-10 concurrent agents

Future Scaling

• Horizontal: Multiple agent instances
• Separate: MCP servers in containers
• Database: Persistent state store
• Queue: Asynchronous job processing

Security Considerations

For Learning

• Local development (no external exposure)
• Simple authentication
• Test data only

Production (Not implemented)

• TLS/HTTPS encryption
• IAM-based access control
• Secrets management (AWS Secrets Manager)
• API key rotation
• Audit logging

Next Steps

• 📖 Microservices Architecture - Detailed service breakdown
• 🔗 Event Sourcing - Event-driven patterns
• 🏃 Start Exercise 1 - Learn by doing!