# BlackRoad OS v0 - Router Analysis & Categorization

**Generated**: 2025-11-18
**Branch**: `claude/go-cece-go-016Tb6VLbDJmjyvatTkSeZxY`
**Purpose**: Define which routers are KEEP/PARK/CUT for v0 thin vertical slice

---

## Executive Summary

**Total Routers**: 36
**Frontend-Called Routers**: 10
**v0 KEEP Routers**: 11 (10 frontend + 1 health)
**PARK Routers**: 14 (large, not v0-critical)
**CUT Routers**: 11 (small stubs, experimental)

---

## KEEP: Core v0 Routers (11 total)

These routers are **actively called by the frontend** or **critical for v0 operation**.

| Router | Prefix | Lines | Called By | Purpose |
|--------|--------|-------|-----------|---------|
| **auth** | `/api/auth` | ~200 | Frontend | Login, register, logout, session management |
| **blockchain** | `/api/blockchain` | ~450 | Frontend | Wallet, transactions, blocks, mining |
| **miner** | `/api/miner` | ~300 | Frontend | Mining status, control, pool management |
| **devices** | `/api/devices` | 643 | Frontend | Raspberry Pi, IoT device management |
| **email** | `/api/email` | ~250 | Frontend | RoadMail inbox, sent, compose |
| **social** | `/api/social` | ~300 | Frontend | BlackRoad Social feed, posts, likes, comments |
| **video** | `/api/videos` | ~250 | Frontend | BlackStream videos, likes, views |
| **ai_chat** | `/api/ai-chat` | ~350 | Frontend | AI conversations, messages |
| **files** | `/api/files` | ~200 | Frontend | File manager, folders, uploads |
| **system** | `/api/system` | 83 | Frontend | OS version, config, state |
| **`/health`** | `/health` | (in main.py) | Railway, monitoring | Health check for deployment |

**Action**: ✅ **KEEP** - These must remain active for v0.

---

## CONSIDER: Potentially Useful (3 total)

These routers are **substantial** but **not currently called by frontend**. Evaluate case-by-case.

| Router | Prefix | Lines | Purpose | Decision |
|--------|--------|-------|---------|----------|
| **dashboard** | `/api/dashboard` | 519 | Unified services overview, aggregates stats from all apps | **PARK** - Useful but not v0-critical |
| **agents** | `/api/agents` | 347 | Exposes 208-agent library via API | **PARK** - Cool feature, but not v0-critical |
| **api_health** | `/api/health` | 389 | Service health monitoring, uptime tracking | **PARK** - Overlaps with `/health`, not critical |

**Action**: ⚠️ **PARK** - Move to `_archive/`, can restore later.

---

## PARK: Integration Routers (11 total)

These are **API integration routers** for external services. Not needed for v0 core functionality.

| Router | Prefix | Lines | Purpose |
|--------|--------|-------|---------|
| **railway** | `/api/railway` | 395 | Railway deployment management |
| **vercel** | `/api/vercel` | 426 | Vercel project automation |
| **stripe** | `/api/stripe` | ~300 | Payment processing |
| **twilio** | `/api/twilio` | ~200 | SMS/phone messaging |
| **slack** | `/api/slack` | ~250 | Slack workspace automation |
| **discord** | `/api/discord` | ~250 | Discord community integrations |
| **sentry** | `/api/sentry` | 382 | Error monitoring hooks |
| **github** | `/api/github` | 433 | GitHub automation, repos, issues |
| **huggingface** | `/api/huggingface` | ~200 | AI model integrations |
| **digitalocean** | `/api/digitalocean` | ~350 | DigitalOcean droplets, domains |
| **cloudflare** | `/api/cloudflare` | ~300 | Cloudflare DNS, zones, workers |

**Action**: 📦 **PARK** - Move to `backend/app/routers/_integrations/`, comment out in `main.py`.

---

## CUT: Experimental/Stub Routers (11 total)

These are **small routers** (36-150 lines) that are experimental, incomplete, or not wired to frontend.

| Router | Prefix | Lines | Purpose | Status |
|--------|--------|-------|---------|--------|
| **browser** | `/api/browser` | 414 | In-OS browser (not in frontend) | Stub |
| **games** | `/api/games` | 491 | Gaming platform (not in frontend) | Stub |
| **vscode** | `/api/vscode` | ~200 | VSCode integration (not in frontend) | Stub |
| **capture** | `/api/capture` | 150 | Screen/video capture | Minimal |
| **compliance_ops** | `/api/compliance` | 36 | Compliance operations | Minimal stub |
| **creator** | `/api/creator` | 85 | Creator tools | Minimal stub |
| **identity_center** | `/api/identity` | 123 | Identity management | Minimal stub |
| **notifications_center** | `/api/notifications` | 81 | Notification center | Minimal stub |
| **search** | `/api/search` | 88 | Global search | Minimal stub |
| **operator_webhooks** | `/api/operator/webhooks` | 81 | Operator webhooks | Minimal stub |
| **webhooks** | `/api/webhooks` | ~100 | GitHub webhooks (Phase Q) | Experimental |
| **prism_static** | `/prism/*` | 89 | Prism console static files | Separate app |

**Action**: ✂️ **CUT** - Comment out in `main.py`, move to `backend/app/routers/_experimental/` or delete.

---

## Frontend API Call Map

**All API calls found in `backend/static/js/` (extracted from api-client.js + apps.js + auth.js + core-os-client.js):**

### Auth
- `POST /api/auth/register`
- `POST /api/auth/login`
- `POST /api/auth/logout`
- `GET /api/auth/me`

### Blockchain
- `GET /api/blockchain/wallet`
- `GET /api/blockchain/balance`
- `GET /api/blockchain/transactions`
- `GET /api/blockchain/transactions/{txHash}`
- `POST /api/blockchain/transactions`
- `GET /api/blockchain/blocks`
- `GET /api/blockchain/blocks/{blockId}`
- `POST /api/blockchain/mine`
- `GET /api/blockchain/stats`

### Miner
- `GET /api/miner/status`
- `GET /api/miner/stats`
- `GET /api/miner/blocks`
- `POST /api/miner/control`
- `GET /api/miner/pool/info`

### Devices
- `GET /api/devices/`
- `GET /api/devices/stats`
- `GET /api/devices/{deviceId}`
- `POST /api/devices/`
- `PUT /api/devices/{deviceId}`
- `DELETE /api/devices/{deviceId}`

### Email
- `GET /api/email/folders`
- `GET /api/email/inbox`
- `GET /api/email/sent`
- `GET /api/email/{emailId}`
- `POST /api/email/send`
- `DELETE /api/email/{emailId}`

### Social
- `GET /api/social/feed`
- `POST /api/social/posts`
- `POST /api/social/posts/{postId}/like`
- `GET /api/social/posts/{postId}/comments`
- `POST /api/social/posts/{postId}/comments`
- `POST /api/social/users/{userId}/follow`

### Video
- `GET /api/videos`
- `GET /api/videos/{videoId}`
- `POST /api/videos/{videoId}/like`

### AI Chat
- `GET /api/ai-chat/conversations`
- `POST /api/ai-chat/conversations`
- `GET /api/ai-chat/conversations/{conversationId}`
- `GET /api/ai-chat/conversations/{conversationId}/messages`
- `POST /api/ai-chat/conversations/{conversationId}/messages`
- `DELETE /api/ai-chat/conversations/{conversationId}`

### Files
- `GET /api/files/folders`
- `GET /api/files`
- `GET /api/files/{fileId}`
- `DELETE /api/files/{fileId}`

### System
- `GET /api/system/version`
- `GET /api/system/config/public`
- `GET /api/system/os/state`

### Health
- `GET /health` (core endpoint, not in a router)

---

## Routers NOT Called by Frontend

**These 25 routers exist but are not called by current frontend:**

agents, api_health, browser, capture, cloudflare, compliance_ops, creator, dashboard, digitalocean, discord, games, github, huggingface, identity_center, notifications_center, operator_webhooks, prism_static, railway, search, sentry, slack, stripe, twilio, vercel, vscode, webhooks

---

## Recommendations for v0

### Immediate Actions

1. **Keep these 11 routers active:**
   - auth, blockchain, miner, devices, email, social, video, ai_chat, files, system
   - Plus `/health` endpoint in `main.py`

2. **Move integrations to `_integrations/`:**
   - Create `backend/app/routers/_integrations/`
   - Move: railway, vercel, stripe, twilio, slack, discord, sentry, github, huggingface, digitalocean, cloudflare
   - Comment out in `main.py`

3. **Move experimental to `_experimental/`:**
   - Create `backend/app/routers/_experimental/`
   - Move: browser, games, vscode, capture, compliance_ops, creator, identity_center, notifications_center, search, operator_webhooks, webhooks, prism_static
   - Comment out in `main.py`

4. **Park potentially useful routers:**
   - Move dashboard, agents, api_health to `_experimental/` for now
   - Can restore later when frontend needs them

### Database Dependencies

**Check these models are needed for KEEP routers:**
- User (auth)
- Block, Transaction, Wallet (blockchain)
- Device (devices)
- Email (email)
- Post, Like, Comment (social)
- Video (video)
- Conversation, Message (ai_chat)
- File, Folder (files)

**Models for PARK/CUT routers can be left in place** (no harm, just unused).

### Environment Variables

**Required for v0 KEEP routers:**
- `SECRET_KEY` (auth)
- `DATABASE_URL` (all routers)
- `REDIS_URL` (sessions, caching)
- `OPENAI_API_KEY` (ai_chat)
- `SMTP_*` variables (email - optional if email is stub)
- `AWS_*` variables (files - optional if files is stub)

**Not required for v0:**
- `STRIPE_*`, `TWILIO_*`, `SLACK_*`, `DISCORD_*`, `GITHUB_*`, etc. (all integration routers)

---

## Testing Strategy

**After reorganization, test:**

1. **Start backend**: `uvicorn app.main:app --reload`
2. **Check startup logs**: No import errors for moved routers
3. **Hit `/health`**: Returns `{"status": "healthy"}`
4. **Load frontend**: `http://localhost:8000/`
5. **Test auth**: Register/login works
6. **Test one app**: e.g., Wallet or AI Chat
7. **Check browser console**: No 404 errors for API calls

---

## Next Steps

See `ROUTER_PLAN.md` for detailed execution plan.

---

**End of Router Analysis**