24f3001764/llm_code_deployment
0
1# System Architecture2 3## Overview4 5```6┌─────────────────────────────────────────────────────────────────┐7│ Instructor System │8│ (Sends Task Request via POST) │9└────────────────────────────┬────────────────────────────────────┘10 │11 │ POST /request12 │ {email, secret, task, brief, ...}13 ▼14┌─────────────────────────────────────────────────────────────────┐15│ Student API Server (FastAPI) │16│ │17│ ┌──────────────────────────────────────────────────────────┐ │18│ │ main.py - Request Handler │ │19│ │ • Validates secret │ │20│ │ • Returns HTTP 200 immediately │ │21│ │ • Spawns background task │ │22│ └──────────────────────────────────────────────────────────┘ │23│ │ │24│ │ Background Processing │25│ ▼ │26│ ┌──────────────────────────────────────────────────────────┐ │27│ │ utils.py - Attachment Handler │ │28│ │ • Decodes base64 data URIs │ │29│ │ • Saves attachments to disk │ │30│ └──────────────────────────────────────────────────────────┘ │31│ │ │32│ ▼ │33│ ┌──────────────────────────────────────────────────────────┐ │34│ │ llm_generator.py - App Generator │ │35│ │ • Builds prompt from brief + checks │ │36│ │ • Calls OpenAI GPT-4 API │ │37│ │ • Generates HTML/CSS/JS app │ │38│ │ • Generates README.md │ │39│ └──────────────────────────────────────────────────────────┘ │40│ │ │41│ ▼ │42│ ┌──────────────────────────────────────────────────────────┐ │43│ │ github_manager.py - GitHub Integration │ │44│ │ • Creates public repository │ │45│ │ • Adds MIT LICENSE │ │46│ │ • Pushes generated code │ │47│ │ • Enables GitHub Pages │ │48│ │ • Returns repo URL, commit SHA, pages URL │ │49│ └──────────────────────────────────────────────────────────┘ │50│ │ │51│ ▼ │52│ ┌──────────────────────────────────────────────────────────┐ │53│ │ evaluator.py - Notification Handler │ │54│ │ • POSTs to evaluation_url │ │55│ │ • Includes repo details + request metadata │ │56│ │ • Retries with exponential backoff (1,2,4,8,16s) │ │57│ └──────────────────────────────────────────────────────────┘ │58│ │ │59└─────────────────────────────┼─────────────────────────────────────┘60 │61 │ POST to evaluation_url62 │ {email, task, repo_url, ...}63 ▼64┌─────────────────────────────────────────────────────────────────┐65│ Instructor Evaluation API │66│ (Receives Notification) │67└─────────────────────────────────────────────────────────────────┘68```69 70## Component Details71 72### 1. FastAPI Server (`main.py`)73**Responsibilities:**74- Accept incoming HTTP POST requests75- Validate student secret76- Return immediate HTTP 200 response77- Spawn background tasks for processing78- Track task state79- Provide status endpoint80 81**Key Endpoints:**82- `GET /` - Health check83- `POST /request` - Main task endpoint84- `GET /status/{task_id}` - Task status85 86### 2. Data Models (`models.py`)87**Structures:**88- `TaskRequest` - Incoming request schema89- `EvaluationPayload` - Outgoing notification schema90- `APIResponse` - Immediate response schema91- `Attachment` - Attachment data structure92 93### 3. Configuration (`config.py`)94**Manages:**95- Environment variables96- API keys (OpenAI, GitHub)97- Student secret98- Timeouts and retry delays99- Directory paths100 101### 4. Utilities (`utils.py`)102**Functions:**103- `decode_and_save_attachments()` - Handle data URIs104- `sanitize_repo_name()` - Clean task IDs for GitHub105- `get_mit_license()` - Return MIT license text106 107### 5. LLM Generator (`llm_generator.py`)108**Process:**1091. Build prompt from brief, checks, attachments1102. Call OpenAI GPT-4 API1113. Parse and clean response1124. Generate HTML/CSS/JS application1135. Generate professional README.md1146. Save files to disk115 116**Fallback:**117- If API fails, uses template HTML118- Ensures app is always generated119 120### 6. GitHub Manager (`github_manager.py`)121**Round 1 (Create):**1221. Check if repo exists (delete if testing)1232. Create new public repository1243. Add LICENSE file1254. Add README.md1265. Add index.html1276. Enable GitHub Pages1287. Wait for deployment1298. Return URLs and commit SHA130 131**Round 2 (Update):**1321. Get existing repository1332. Update README.md1343. Update index.html1354. Commit changes1365. Wait for redeployment1376. Return new commit SHA138 139### 7. Evaluator (`evaluator.py`)140**Notification Process:**1411. Prepare JSON payload1422. POST to evaluation_url1433. Check for HTTP 200 response1444. If failed, retry with delays: 1s, 2s, 4s, 8s, 16s1455. Log all attempts1466. Return success/failure status147 148## Data Flow149 150### Round 1: Build and Deploy151 152```153Request → Validate → Save Attachments → Generate App → Create Repo154 ↓155Notify ← Wait ← Enable Pages ← Push Code ← Add Files ← Create Repo156```157 158**Timeline:**159- 0s: Request received, 200 returned160- 0-30s: LLM generates app161- 30-40s: GitHub repo created162- 40-50s: Pages enabled, waiting for deployment163- 50-60s: Notification sent164- Total: ~1 minute165 166### Round 2: Revise167 168```169Request → Validate → Save Attachments → Generate Updated App170 ↓171Notify ← Wait ← Redeploy Pages ← Update Files ← Get Repo172```173 174**Timeline:**175- 0s: Request received, 200 returned176- 0-30s: LLM generates updated app177- 30-40s: Files updated in repo178- 40-50s: Pages redeployed179- 50-60s: Notification sent180- Total: ~1 minute181 182## External Dependencies183 184### OpenAI API185- **Model:** GPT-4 Turbo Preview186- **Usage:** Generate HTML/CSS/JS and README187- **Rate Limits:** Depends on account tier188- **Cost:** ~$0.01-0.03 per request189 190### GitHub API191- **Library:** PyGithub192- **Operations:** Create repo, add files, enable Pages193- **Rate Limits:** 5000/hour (authenticated)194- **Requirements:** Personal Access Token with `repo` scope195 196### Evaluation API197- **Protocol:** HTTP POST with JSON198- **Expected Response:** HTTP 200199- **Retry Logic:** Exponential backoff200- **Timeout:** 30 seconds per attempt201 202## State Management203 204### In-Memory State (Development)205```python206task_state = {207 "task-id-1": {208 "status": "completed",209 "started_at": "2025-10-10T12:00:00",210 "completed_at": "2025-10-10T12:01:00",211 "repo_url": "https://github.com/user/task-id",212 "pages_url": "https://user.github.io/task-id/",213 "notification_sent": True214 }215}216```217 218### Production Considerations219- Use database (PostgreSQL, MongoDB)220- Add task queue (Celery, RQ)221- Implement webhooks for async updates222- Add monitoring and alerting223 224## Security Measures225 226### Secret Management227- Student secret stored in environment variable228- Validated on every request229- Never logged or exposed230 231### API Keys232- Stored in `.env` file (gitignored)233- Loaded via python-dotenv234- Never committed to git235 236### GitHub Token237- Minimal required scopes (`repo`, `workflow`)238- Stored securely239- Can be rotated if compromised240 241### Input Validation242- Pydantic models validate all inputs243- Sanitize repo names244- Validate data URIs245- Check file sizes (future enhancement)246 247## Error Handling248 249### Request Level250- Invalid secret → HTTP 401251- Missing fields → HTTP 422 (Pydantic validation)252- Server error → HTTP 500253 254### Background Processing255- LLM API failure → Use fallback template256- GitHub API failure → Log error, mark task failed257- Notification failure → Retry with backoff258 259### Logging260- INFO: Normal operations261- WARNING: Retries, non-critical issues262- ERROR: Failures, exceptions263- All logs include task ID for tracing264 265## Scalability Considerations266 267### Current Limitations268- In-memory state (lost on restart)269- Synchronous background tasks270- No request queuing271- Single server instance272 273### Scaling Solutions2741. **Database:** PostgreSQL for persistent state2752. **Queue:** Redis + Celery for task processing2763. **Load Balancer:** Multiple API instances2774. **Caching:** Redis for frequently accessed data2785. **Monitoring:** Prometheus + Grafana2796. **Logging:** ELK stack or CloudWatch280 281## Deployment Architecture282 283### Development284```285Local Machine → FastAPI (localhost:8000)286```287 288### Production (Cloud)289```290Internet → Load Balancer → API Servers (multiple)291 ↓292 Task Queue (Redis/Celery)293 ↓294 Database (PostgreSQL)295```296 297## Testing Strategy298 299### Unit Tests300- Test each module independently301- Mock external APIs302- Validate data models303 304### Integration Tests305- Test API endpoints306- Test GitHub integration307- Test LLM generation308 309### End-to-End Tests310- Full workflow from request to notification311- Test both Round 1 and Round 2312- Verify GitHub Pages deployment313 314### Manual Testing315- Use `test_client.py`316- Test with various briefs317- Test error scenarios318- Verify logs and state319 320## Monitoring321 322### Key Metrics323- Request count324- Success/failure rate325- Average processing time326- API error rates (OpenAI, GitHub)327- Notification success rate328 329### Health Checks330- API server status331- Database connectivity (if used)332- External API availability333- Disk space for generated apps334 335### Alerts336- High error rate337- API quota exceeded338- Deployment failures339- Long processing times (>10 min)340 341---342 343**This architecture supports the complete TDS Project 1 workflow while remaining simple enough for students to understand and extend.**344