docs/module-2/README.md

# Topcoder Challenge Steward Agent – Module 2 Architecture

This module describes the split architecture for the Topcoder Challenge Steward Agent, separating the user interface and backend agent logic.

---

## 1. User Interface (Frontend)

- **Framework:** [NestJS](https://nestjs.com/) (API/backend) + [Material UI](https://mui.com/) (React-based UI)
- **Purpose:**
  - Allow users to provide their challenge preferences (free text, tags, etc.)
  - Allow users to start/stop the agent for themselves
  - Simple, clean interface for managing notification settings
- **Key Features:**
  - User authentication (optional, depending on deployment)
  - Form for entering/editing preferences
  - Button(s) to start/stop the agent
  - Status display (agent running, last run, etc.)
  - Communicates with the backend via REST API

---

## 2. Backend (Agent & API)

- **Framework:** [FastAPI](https://fastapi.tiangolo.com/) (Python)
- **Purpose:**
  - Store user preferences and email addresses in a database
  - Expose REST API endpoints for the frontend (CRUD for preferences, agent control)
  - Run the agent on a schedule (e.g., daily per user)
  - Poll the database for active agents and execute them
  - For each active agent:
    - Retrieve user preferences
    - Combine with system prompt
    - Run the agent logic (implemented in Python, with MCP integration)
    - Send notifications via Email MCP if suitable challenges are found
- **Key Features:**
  - User management (basic, for mapping preferences to emails)
  - Preference storage (database: e.g., SQLite, PostgreSQL, etc.)
  - Scheduler (e.g., Celery, APScheduler, or FastAPI background tasks)
  - Integration with Topcoder MCP (fetch challenges, skills, etc.)
  - Integration with Email MCP (send notifications)

---

## System Flow Diagram

```mermaid
graph TD
  A[User] -- Preferences/Control --> B[Frontend (NestJS + Material UI)]
  B -- REST API --> C[Backend (FastAPI)]
  C -- Store/Retrieve --> D[(Database)]
  C -- Schedule/Run --> E[Agent Logic]
  E -- Fetch Challenges --> F[Topcoder MCP]
  E -- Send Email --> G[Email MCP]
```

---

## Development Notes
- The frontend and backend are decoupled and communicate via HTTP REST APIs.
- The backend is responsible for all agent execution and persistence.
- The agent logic is implemented in Python for easy integration with AI/ML libraries and MCP services.
- The system is designed for extensibility (e.g., adding more notification channels, richer preference models). 

---

## Deploying to Hugging Face Spaces as a Single Docker Container

I can deploy this full-stack (NestJS + Material UI frontend, FastAPI backend) app as a single Docker container on Hugging Face Spaces. Below are the recommended steps and best practices:

### 1. Project Structure
- I will place all code (frontend and backend) in the repository.
- I will include a `Dockerfile` and `README.md` (with Hugging Face metadata).
- I will add `requirements.txt` for Python dependencies and `package.json`/`yarn.lock` for Node dependencies if building the frontend in Docker.

### 2. Dockerfile Example (Multi-Stage Build)

```dockerfile
# Stage 1: Build frontend
FROM node:18 AS frontend-build
WORKDIR /app/frontend
COPY frontend/ .
RUN npm install && npm run build

# Stage 2: Build backend
FROM python:3.9 AS backend
RUN useradd -m -u 1000 user
WORKDIR /app

# Install Python dependencies
COPY --chown=user requirements.txt .
RUN pip install --no-cache-dir --upgrade -r requirements.txt

# Copy backend code
COPY --chown=user backend/ /app/backend

# Copy built frontend to backend's static directory
COPY --from=frontend-build /app/frontend/build /app/backend/static

# Set permissions
USER user
ENV HOME=/home/user PATH=/home/user/.local/bin:$PATH

# Expose the port expected by Hugging Face Spaces
EXPOSE 7860

# Start FastAPI (serving both API and static frontend)
CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "7860"]
```

- I will adjust paths as needed for my project layout.
- If I want to use Nginx or another server for static files, I will add a third stage.

### 3. Hugging Face README Metadata Block
I will add this YAML block at the top of my `README.md`:

```yaml
---
title: Topcoder Challenge Steward Agent
emoji: 🏗️
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
---
```

### 4. Data Persistence
- By default, data is not persisted between restarts.
- For persistent storage, I will use the `supabase` free tier https://supabase.com/pricing directory or an external database.

### 5. Environment Variables & Secrets
- I will set secrets and environment variables in the Hugging Face Space settings.
- I will access them in my code via `os.environ` (Python) or `process.env` (Node.js).

### 6. Build & Push
- I will push my code to my Hugging Face Space repository.
- The Space will build and run my Dockerfile automatically.

#### References
- [Hugging Face: Your First Docker Space](https://huggingface.co/docs/hub/spaces-sdks-docker-first-demo)
- [Hugging Face: Docker Spaces Documentation](https://huggingface.co/docs/hub/spaces-sdks-docker)
- [Permissions & User Setup](https://huggingface.co/docs/hub/spaces-sdks-docker#permissions)
- [Persistent Storage](https://huggingface.co/docs/hub/spaces-sdks-docker#data-persistence)