blackroad-operating-system/ROUTER_PLAN.md

BlackRoad OS v0 - Router Cleanup Execution Plan

Generated: 2025-11-18 Branch: claude/go-cece-go-016Tb6VLbDJmjyvatTkSeZxY Based On: CORE_ROUTERS.md analysis Estimated Time: 2-3 hours (across 7 phases)

---

Overview

Goal: Reduce backend from 36 routers to 11 core routers for v0.

Strategy: Surgical refactor - move routers to organized directories, comment out in main.py, preserve all code for later.

Outcome: Clean v0 boundary, reliable Railway deploy, maintainable codebase.

---

Phase 1: Create Archive Directories (5 min)

Tasks

1. Create directory structure:

   mkdir -p backend/app/routers/_integrations
   mkdir -p backend/app/routers/_experimental
   

2. Create README files:

   backend/app/routers/_integrations/README.md:

   # Integration Routers (Parked for Post-v0)
   
   These routers provide integrations with external services:
   - Railway, Vercel, Stripe, Twilio, Slack, Discord, Sentry
   - GitHub, HuggingFace, DigitalOcean, Cloudflare
   
   **Status**: Not required for v0. Can be restored when needed.
   **How to restore**: Move router file back to parent directory, uncomment in main.py.
   

   backend/app/routers/_experimental/README.md:

   # Experimental Routers (Parked for Post-v0)
   
   These routers are experimental, incomplete, or not yet wired to frontend:
   - browser, games, vscode - Future apps
   - capture, compliance_ops, creator, identity_center, notifications_center, search - Minimal stubs
   - operator_webhooks, webhooks, prism_static - Infrastructure features
   - dashboard, agents, api_health - Potentially useful, not v0-critical
   
   **Status**: Experimental. Can be restored when needed.
   **How to restore**: Move router file back to parent directory, uncomment in main.py.
   

Success Criteria

• ✅ Directories exist
• ✅ README files in place

---

Phase 2: Move Integration Routers (10 min)

Tasks

Move these 11 routers to _integrations/:

cd backend/app/routers

mv railway.py _integrations/
mv vercel.py _integrations/
mv stripe.py _integrations/
mv twilio.py _integrations/
mv slack.py _integrations/
mv discord.py _integrations/
mv sentry.py _integrations/
mv github.py _integrations/
mv huggingface.py _integrations/
mv digitalocean.py _integrations/
mv cloudflare.py _integrations/

Success Criteria

• ✅ 11 files moved to _integrations/
• ✅ Original locations empty

---

Phase 3: Move Experimental Routers (10 min)

Tasks

Move these 14 routers to _experimental/:

cd backend/app/routers

mv browser.py _experimental/
mv games.py _experimental/
mv vscode.py _experimental/
mv capture.py _experimental/
mv compliance_ops.py _experimental/
mv creator.py _experimental/
mv identity_center.py _experimental/
mv notifications_center.py _experimental/
mv search.py _experimental/
mv operator_webhooks.py _experimental/
mv webhooks.py _experimental/
mv prism_static.py _experimental/
mv dashboard.py _experimental/
mv agents.py _experimental/
mv api_health.py _experimental/

Success Criteria

• ✅ 14 files moved to _experimental/
• ✅ Original locations empty

---

Phase 4: Update main.py Imports (15 min)

Tasks

Current main.py imports (lines 13-19):

from app.routers import (
    auth, email, social, video, files, blockchain, ai_chat, devices, miner,
    digitalocean, github, huggingface, vscode, games, browser, dashboard,
    railway, vercel, stripe, twilio, slack, discord, sentry, api_health, agents,
    capture, identity_center, notifications_center, creator, compliance_ops,
    search, cloudflare, system, webhooks
    search, cloudflare, prism_static
)

New main.py imports (KEEP only):

from app.routers import (
    auth, email, social, video, files, blockchain, ai_chat, devices, miner, system
)

Full edit:

Find this block (lines 13-20):

from app.routers import (
    auth, email, social, video, files, blockchain, ai_chat, devices, miner,
    digitalocean, github, huggingface, vscode, games, browser, dashboard,
    railway, vercel, stripe, twilio, slack, discord, sentry, api_health, agents,
    capture, identity_center, notifications_center, creator, compliance_ops,
    search, cloudflare, system, webhooks
    search, cloudflare, prism_static
)

Replace with:

from app.routers import (
    auth, email, social, video, files, blockchain, ai_chat, devices, miner, system
)

# Integrations (parked for post-v0)
# from app.routers._integrations import (
#     railway, vercel, stripe, twilio, slack, discord, sentry,
#     github, huggingface, digitalocean, cloudflare
# )

# Experimental (parked for post-v0)
# from app.routers._experimental import (
#     browser, games, vscode, capture, compliance_ops, creator,
#     identity_center, notifications_center, search, operator_webhooks,
#     webhooks, prism_static, dashboard, agents, api_health
# )

Update router registrations (lines 121-171):

Comment out all non-KEEP router registrations:

KEEP these (10 routers):

app.include_router(auth.router)
app.include_router(email.router)
app.include_router(social.router)
app.include_router(video.router)
app.include_router(files.router)
app.include_router(blockchain.router)
app.include_router(ai_chat.router)
app.include_router(devices.router)
app.include_router(miner.router)
app.include_router(system.router)

COMMENT OUT these (26 routers):

# Integration routers (parked for post-v0)
# app.include_router(digitalocean.router)
# app.include_router(github.router)
# app.include_router(huggingface.router)
# app.include_router(railway.router)
# app.include_router(vercel.router)
# app.include_router(stripe.router)
# app.include_router(twilio.router)
# app.include_router(slack.router)
# app.include_router(discord.router)
# app.include_router(sentry.router)
# app.include_router(cloudflare.router)

# Experimental routers (parked for post-v0)
# app.include_router(vscode.router)
# app.include_router(games.router)
# app.include_router(browser.router)
# app.include_router(dashboard.router)
# app.include_router(capture.router)
# app.include_router(identity_center.router)
# app.include_router(notifications_center.router)
# app.include_router(creator.router)
# app.include_router(compliance_ops.router)
# app.include_router(search.router)
# app.include_router(api_health.router)
# app.include_router(agents.router)
# app.include_router(webhooks.router)
# app.include_router(prism_static.router)

Also remove Prism static mount (lines 165-171):

# Prism Console (Phase 2.5) - Parked for post-v0
# prism_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), "prism-console")
# if os.path.exists(prism_dir):
#     app.mount("/prism", StaticFiles(directory=prism_dir, html=True), name="prism")
#     print(f"✅ Prism Console mounted at /prism")

Success Criteria

• ✅ Only 10 routers imported
• ✅ Only 10 routers registered
• ✅ 25+ routers commented out with clear labels
• ✅ Prism mount commented out

---

Phase 5: Test Backend Startup (10 min)

Tasks

1. Start backend:

   cd backend
   uvicorn app.main:app --reload
   

2. Check startup output:

   • No import errors
   • Database tables created successfully
   • Server running message
   • No missing module errors

3. Test health endpoint:

   curl http://localhost:8000/health
   

   Expected: {"status":"healthy","timestamp":...}

4. Check API docs:

   • Visit: http://localhost:8000/api/docs
   • Verify only 10 router groups visible:
     • auth, email, social, video, files, blockchain, ai_chat, devices, miner, system
   • No integration/experimental routers visible

Success Criteria

• ✅ Backend starts without errors
• ✅ /health returns 200
• ✅ API docs show only 10 router groups
• ✅ No 404s or import errors in console

---

Phase 6: Test Frontend Integration (15 min)

Tasks

1. Load frontend:

   • Visit: http://localhost:8000/
   • Should see BlackRoad OS desktop

2. Test authentication:

   • Click "Register" → Create account → Should succeed
   • Login with new account → Should succeed
   • Desktop should load after login

3. Test one app (Wallet):

   • Double-click "Wallet" icon
   • Window should open
   • Should see wallet address, balance (may be 0)
   • No console errors

4. Check browser console:

   • Open DevTools → Console tab
   • Should see no 404 errors
   • Should see no "Failed to fetch" errors for core endpoints

5. Test AI Chat (if OpenAI key set):

   • Double-click "AI Chat" icon
   • Should see "New Conversation" button
   • Create conversation → Should succeed
   • Send message → Should get response (or clear error if no API key)

Success Criteria

• ✅ Frontend loads
• ✅ Auth works (register + login)
• ✅ At least one app works end-to-end
• ✅ No console errors for core API calls
• ✅ No 404s for missing routers

---

Phase 7: Run Backend Tests (15 min)

Tasks

1. Run test suite:

   cd backend
   source .venv-tests/bin/activate  # or create new venv
   pytest -v --maxfail=1
   

2. Check test results:

   • Tests for KEEP routers should pass:
     • test_auth.py (register, login, logout)
     • test_blockchain.py (wallet, transactions, blocks)
     • test_miner.py (status, control)
   • Tests for PARK/CUT routers may fail (expected - we removed them)

3. Document failing tests:

   • If tests fail for PARK/CUT routers, that's OK
   • If tests fail for KEEP routers, investigate

Success Criteria

• ✅ At least 50% of tests pass
• ✅ No tests fail for KEEP routers
• ✅ Failing tests are only for PARK/CUT routers

---

Phase 8: Update Documentation (10 min)

Tasks

1. Update CLAUDE.md:

   • Add note: "As of 2025-11-18, v0 uses 10 core routers. Integration and experimental routers are parked in _integrations/ and _experimental/."
   • Update router count from "33+ routers" to "10 core routers (25+ parked)"

2. Update README.md:

   • Add section on v0 scope
   • List active features:
     • Authentication
     • Blockchain & Mining
     • Devices (IoT)
     • Email
     • Social Feed
     • Video Streaming
     • AI Chat
     • File Manager
   • Note: "Additional integrations and features available in post-v0 releases"

3. Create CHANGELOG.md entry:

   ## v0.1.0 - 2025-11-18
   
   ### Changed
   - Reduced backend from 36 routers to 10 core routers for v0 release
   - Moved integration routers (Railway, Vercel, Stripe, etc.) to `_integrations/`
   - Moved experimental routers (browser, games, dashboard, etc.) to `_experimental/`
   
   ### Core Features (v0)
   - ✅ Authentication (register, login, logout)
   - ✅ Blockchain (wallet, transactions, blocks, mining)
   - ✅ Mining (pool management, status, control)
   - ✅ Devices (Raspberry Pi, IoT device management)
   - ✅ Email (RoadMail inbox, compose, send)
   - ✅ Social (BlackRoad Social feed, posts, likes, comments)
   - ✅ Video (BlackStream videos, likes, views)
   - ✅ AI Chat (conversations with AI assistant)
   - ✅ Files (file manager, folders, uploads)
   - ✅ System (OS version, config, state)
   
   ### Parked Features (Post-v0)
   - 🅿️ API Integrations (11 services)
   - 🅿️ Experimental Features (14 routers)
   - 🅿️ Prism Console (admin interface)
   
   ### Technical Improvements
   - Cleaner main.py with organized imports
   - Faster startup (fewer routers to initialize)
   - Smaller API surface area (easier to secure)
   - Clear v0 boundary (easier to extend later)
   

Success Criteria

• ✅ CLAUDE.md updated
• ✅ README.md updated with v0 scope
• ✅ CHANGELOG.md entry added

---

Commit & Push (5 min)

Tasks

1. Stage changes:

   git add backend/app/routers/
   git add backend/app/main.py
   git add CORE_ROUTERS.md ROUTER_PLAN.md
   git add CLAUDE.md README.md CHANGELOG.md
   

2. Commit:

   git commit -m "$(cat <<'EOF'
   Reorganize routers for v0: Keep 10 core, park 25 integrations/experimental
   
   - Move 11 integration routers to _integrations/ (Railway, Stripe, etc.)
   - Move 14 experimental routers to _experimental/ (browser, games, dashboard, etc.)
   - Update main.py to import/register only 10 core routers
   - Add CORE_ROUTERS.md with full analysis and categorization
   - Add ROUTER_PLAN.md with execution plan
   - Update documentation (CLAUDE.md, README.md, CHANGELOG.md)
   
   Core v0 routers:
   - auth, email, social, video, files, blockchain, ai_chat, devices, miner, system
   
   All parked routers preserved and can be restored later.
   Tests pass for core routers. Frontend integration verified.
   EOF
   )"
   

3. Push:

   git push -u origin claude/go-cece-go-016Tb6VLbDJmjyvatTkSeZxY
   

Success Criteria

• ✅ All changes committed
• ✅ Clear commit message
• ✅ Pushed to GitHub

---

Railway Deployment Prep (Phase 9)

Tasks

This phase happens AFTER local testing is successful.

1. Validate .env.example:

   • Ensure it has all required variables for v0:
     • SECRET_KEY
     • DATABASE_URL
     • REDIS_URL
     • OPENAI_API_KEY (optional)
     • SMTP_* (optional)
     • AWS_* (optional)

2. Check Railway env vars:

   • Log into Railway dashboard
   • Verify these are set:
     • DATABASE_URL (Railway Postgres)
     • REDIS_URL (Railway Redis or external)
     • SECRET_KEY (generate if missing)
     • ENVIRONMENT=production
     • DEBUG=False

3. Validate railway.toml:

   • Health check path: /health ✅ (already correct)
   • Dockerfile path: backend/Dockerfile ✅ (already correct)
   • Start command: handled by Dockerfile ✅ (already correct)

4. Test health check locally:

   curl http://localhost:8000/health
   

   Should return: {"status":"healthy","timestamp":...}

Success Criteria

• ✅ .env.example has all required vars
• ✅ Railway env vars are set
• ✅ railway.toml is correct
• ✅ /health endpoint works

---

Railway Deploy (Phase 10)

Tasks

1. Trigger deploy:

   • Push to main branch (or configured branch)
   • Railway auto-deploys
   • Or manual: railway up

2. Monitor build logs:

   • Check Railway dashboard → Deployments
   • Watch for:
     • Docker build success
     • Python dependencies install
     • App startup
     • Health check pass

3. Check deploy status:

   • Railway should show "Healthy" status
   • Health check should pass within 40 seconds

4. Test deployed endpoints:

   # Replace with your Railway URL
   RAILWAY_URL="https://blackroad-os-production.up.railway.app"
   
   curl $RAILWAY_URL/health
   curl $RAILWAY_URL/api
   

5. Test frontend:

   • Visit Railway URL in browser
   • Should see BlackRoad OS desktop
   • Test auth (register/login)
   • Test one app (Wallet or AI Chat)

Success Criteria

• ✅ Deploy succeeds
• ✅ Health check passes
• ✅ /health returns 200
• ✅ Frontend loads
• ✅ Auth works
• ✅ At least one app works

---

Rollback Plan

If something breaks during cleanup:

1. Revert main.py changes:

   git checkout HEAD~1 backend/app/main.py
   

2. Move routers back:

   mv backend/app/routers/_integrations/* backend/app/routers/
   mv backend/app/routers/_experimental/* backend/app/routers/
   

3. Restart backend:

   uvicorn app.main:app --reload
   

4. Test:

   • Should be back to 36 routers
   • All endpoints restored

---

Risk Mitigation

Risk	Likelihood	Impact	Mitigation
Import errors after move	Medium	High	Test locally first, use try/except if needed
Frontend 404s	Low	Medium	Frontend only calls 10 core routers, verified in Phase 1
Database migration fails	Low	High	Not changing DB schema, just router organization
Railway deploy fails	Medium	High	Test locally first, validate env vars, check health endpoint
Missing env var	Medium	Medium	Validate .env.example vs config.py defaults
Redis not available	Low	Medium	Check Railway services, app has Redis URL default

---

Definition of Done

v0 is ready when:

• ✅ Backend has 10 core routers only
• ✅ 25 routers moved to _integrations/ and _experimental/
• ✅ Backend starts without errors locally
• ✅ /health returns 200
• ✅ Frontend loads at /
• ✅ Auth works (register + login)
• ✅ At least 3 apps work (Wallet, AI Chat, Social)
• ✅ No console errors for core API calls
• ✅ Railway deploy succeeds
• ✅ Railway health check passes
• ✅ Documentation updated (CLAUDE.md, README.md, CHANGELOG.md)
• ✅ Changes committed and pushed to GitHub

---

Next Steps After v0

Future roadmap (post-v0):

1. Restore integrations one-by-one:

   • Move router back from _integrations/
   • Uncomment in main.py
   • Add env vars
   • Test integration
   • Document in README

2. Complete experimental features:

   • Browser, Games, VSCode apps
   • Dashboard aggregation
   • Agent API exposure
   • Prism Console

3. Add missing tests:

   • Increase coverage for core routers
   • Add integration tests
   • Add E2E tests

4. Database migration cleanup:

   • Remove Base.metadata.create_all() from startup
   • Use Alembic only (as flagged in CLAUDE.md)
   • Add migration validation to CI

5. Frontend enhancements:

   • Add error boundaries
   • Add loading states
   • Add offline support
   • Add PWA manifest

---

Total Time Estimate

Phase	Time	Cumulative
1. Create directories	5 min	5 min
2. Move integrations	10 min	15 min
3. Move experimental	10 min	25 min
4. Update main.py	15 min	40 min
5. Test backend	10 min	50 min
6. Test frontend	15 min	65 min
7. Run tests	15 min	80 min
8. Update docs	10 min	90 min
9. Commit & push	5 min	95 min
10. Railway prep	10 min	105 min
11. Railway deploy	15 min	120 min

Total: ~2 hours (can be done in phases, doesn't need to be continuous)

---

Phone-Friendly Summary

For quick reference on iPhone:

1. ✅ Move 11 integrations to _integrations/
2. ✅ Move 14 experimental to _experimental/
3. ✅ Update main.py to import only 10 core routers
4. ✅ Test locally (backend + frontend)
5. ✅ Run tests
6. ✅ Update docs
7. ✅ Commit + push
8. ✅ Validate Railway env vars
9. ✅ Deploy to Railway
10. ✅ Test production deploy

Core routers to keep: auth, email, social, video, files, blockchain, ai_chat, devices, miner, system

Everything else goes to _integrations/ or _experimental/

---

End of Execution Plan