scripts

MBTQ Local Development Build-Out Plan
Build Everything on Ubuntu Before Cloud Migration
Overview

 UBUNTU MACHINE
└── Complete MBTQ Ecosystem (local)
├── Frontend Applications
├── 5 Backend Services (FastAPI)
├── All APIs fully functional
├── PostgreSQL + Redis
├── NGINX (local routing only)
├── Mission Control Dashboard
└── Everything tested and working

LATER → Google Cloud Run (when ready)
Current Domains: Leave ALL DNS records alone - they stay live Local Development:

Use localhost or .local domains
Phase 1: Foundation (Week 1-2)
1.1 Directory Structure
/home/pinky/mbtq/
├── frontend/
│ ├── web/ │ ├── admin/ │ └── docs/ ├── backends/
│ ├── deafauth/ │ ├── pinksync/ │ ├── fibonrose/ │ ├── magicians/ │ └── content/ # Main web application
# Admin dashboard
# Documentation site
# Port 4001 - Identity
# Port 4002 - Workflows
# Port 4003 - Reputation
# Port 4004 - AI Processing
# Port 4005 - Media
├── infrastructure/
│ ├── nginx/
│ │ ├── nginx.conf
│ │ └── sites/
│ ├── docker-compose.yml # All services
│ └── init-scripts/
├── shared/
│ ├── types/ # TypeScript/Pydantic types
│ ├── utils/ # Shared utilities
│ └── constants/ # Shared constants
├── mission-control/ # Your dashboard
│ ├── main.py
│ └── templates/
├── docs/ # Architecture docs
├── .env # Master environment
├── .env.example # Template (commit this)
└── .gitignore
1.2 Local Domain Setup
Edit /etc/hosts :
# MBTQ Local Development
127.0.0.1 mbtq.local
127.0.0.1 control.mbtq.local
127.0.0.1 auth.mbtq.local
127.0.0.1 sync.mbtq.local
127.0.0.1 trust.mbtq.local
127.0.0.1 ai.mbtq.local
127.0.0.1 media.mbtq.local
127.0.0.1 api.mbtq.local
1.3 Database Setup
# Install PostgreSQL
sudo apt update
sudo apt install postgresql postgresql-contrib
# Create databases
sudo -u postgres psql << EOF
CREATE USER mbtq WITH PASSWORD 'local_dev_password';
CREATE DATABASE deafauth OWNER mbtq;
CREATE DATABASE pinksync OWNER mbtq;
CREATE DATABASE fibonrose OWNER mbtq;
CREATE DATABASE magicians OWNER mbtq;
CREATE DATABASE content OWNER mbtq;
GRANT ALL PRIVILEGES ON DATABASE deafauth TO mbtq;
GRANT ALL PRIVILEGES ON DATABASE pinksync TO mbtq;
GRANT ALL PRIVILEGES ON DATABASE fibonrose TO mbtq;
GRANT ALL PRIVILEGES ON DATABASE magicians TO mbtq;
GRANT ALL PRIVILEGES ON DATABASE content TO mbtq;

EOF
# Install Redis
sudo apt install redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-server
Phase 2: Backend Development (Week 3-6)
2.1 Backend Template (Apply to All 5)
# backends/deafauth/main.py
from fastapi import FastAPI, Depends, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker
import redis.asyncio as redis
from pydantic_settings import BaseSettings
# Configuration
class Settings(BaseSettings):
service_name: str = "deafauth"
port: int = 4001
database_url: str
redis_url: str
jwt_secret: str
class Config:
env_file = ".env"
settings = Settings()
# Database
engine = create_async_engine(settings.database_url)
AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
# Redis
redis_client = redis.from_url(settings.redis_url)
# FastAPI App
app = FastAPI(
title=f"MBTQ {settings.service_name}",
version="1.0.0",
docs_url=f"/docs",
redoc_url=f"/redoc"
)
# CORS - Allow all during local dev
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3000", "http://mbtq.local"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Health Check
@app.get("/health")
async def health_check():
return {
"service": settings.service_name,
"status": "healthy",
"port": settings.port
}
# Database dependency
async def get_db():
async with AsyncSessionLocal() as session:
yield session
# Example endpoint
@app.get("/")
async def root():
return {
"service": settings.service_name,
"message": "MBTQ Backend Service",
"docs": f"/docs"
}
# Run with: uvicorn main:app --host 0.0.0.0 --port 4001 --reload
2.2 Build Order
Week 3: DeafAUTH (Identity)
✓ User registration
✓ Login/logout
✓ JWT token generation
✓ Token validation endpoint
✓ Session management
✓ Password reset flow
Week 4: PinkSync (Workflows)
✓ GitHub webhook receiver
✓ Workflow trigger system
✓ Job queue (using Redis)
✓ Background task processing
✓ Deployment automation
✓ Status tracking
Week 5: Fibonrose (Reputation)
✓ Reputation scoring algorithm
✓ Badge system
✓ Trust calculation
✓ Community validation
✓ Reputation history
Week 6: Magicians + Content
Magicians:
✓ Anthropic API integration
✓ Video analysis
✓ Annotation extraction
✓ AI agent orchestration
Content:
✓ File upload
✓ Video streaming
✓ Thumbnail generation
✓ Media metadata storage
Phase 3: Frontend Development (Week 7-10)
3.1 Tech Stack Decision
Option A: HTMX (Recommended - Simpler)
Frontend:
├── HTML templates (Jinja2)
├── HTMX for dynamic updates
├── Tailwind CSS for styling
└── Minimal JavaScript
Pros:
✓ Simple to build
✓ Fast development
✓ Works without complex build process
✓ Easy to debug
Option B: React
Frontend:
├── React + TypeScript
├── Vite for bundling
├── React Query for API calls
└── Tailwind CSS
Pros:
✓ Modern UI/UX
✓ Component reusability
✓ Better for complex interactions
3.2 Frontend Structure
frontend/web/
├── public/
│ └── static assets
├── src/
│ ├── components/
│ │ ├── Auth/ # Login, register
│ │ ├── Dashboard/ # Main dashboard
│ │ ├── Profile/ # User profile
│ │ └── Shared/ # Buttons, forms, etc.
│ ├── pages/
│ │ ├── Home.tsx
│ │ ├── Login.tsx
│ │ ├── Dashboard.tsx
│ │ └── Settings.tsx
│ ├── api/
│ │ └── client.ts # API wrapper
│ ├── hooks/
│ │ └── useAuth.ts
│ └── App.tsx
├── package.json
└── vite.config.ts
Phase 4: API Integration (Week 11-12)
4.1 API Client (Shared)
// frontend/src/api/client.ts
const API_BASE = 'http://api.mbtq.local';
class MBTQClient {
private token: string | null = null;
setToken(token: string) {
this.token = token;
localStorage.setItem('mbtq_token', token);
}
async request(endpoint: string, options: RequestInit = {}) {
const headers: HeadersInit = {
'Content-Type': 'application/json',
...(this.token && { Authorization: `Bearer ${this.token}` }),
...options.headers,
};
const response = await fetch(`${API_BASE}${endpoint}`, {
...options,
headers,
});
if (!response.ok) {
throw new Error(`API Error: ${response.statusText}`);
}
return response.json();
}
// Auth endpoints
async login(email: string, password: string) {
const data = await this.request('/auth/login', {
method: 'POST',
body: JSON.stringify({ email, password }),
});
this.setToken(data.access_token);
return data;
}
async register(email: string, password: string, name: string) {
return this.request('/auth/register', {
method: 'POST',
body: JSON.stringify({ email, password, name }),
});
}
// Workflow endpoints
async triggerWorkflow(repo: string, action: string) {
return this.request('/workflows/trigger', {
method: 'POST',
body: JSON.stringify({ repo, action }),
});
// Reputation endpoints
async getReputation(userId: string) {
return this.request(`/reputation/${userId}`);
}
}
// AI endpoints
async processVideo(file: File) {
const formData = new FormData();
formData.append('video', file);
return this.request('/ai/process-video', {
method: 'POST',
body: formData,
headers: {}, // Let browser set Content-Type
});
}
}
export const api = new MBTQClient();
4.2 NGINX API Gateway (Local)
# infrastructure/nginx/sites/api-gateway.conf
# API Gateway - routes to all backends
server {
listen 80;
server_name api.mbtq.local;
# DeafAUTH - Identity
location /auth/ {
proxy_pass http://localhost:4001/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
# PinkSync - Workflows
location /workflows/ {
proxy_pass http://localhost:4002/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
# WebSocket support
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
# Fibonrose - Reputation
location /reputation/ {
proxy_pass http://localhost:4003/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
# Magicians - AI
location /ai/ {
proxy_pass http://localhost:4004/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
# Longer timeout for AI processing
proxy_read_timeout 600s;
}
# Content - Media
location /media/ {
proxy_pass http://localhost:4005/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
# Large file uploads
client_max_body_size 500M;
}
}
# Frontend
server {
listen 80;
server_name mbtq.local;
location / {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
}
}
# Mission Control
server {
listen 80;
server_name control.mbtq.local;
location / {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
}
}
Phase 5: Testing & Validation (Week 13-14)
5.1 Testing Checklist
Backend Tests:
# Each backend needs:
✓ Unit tests (pytest)
✓ Integration tests
✓ API endpoint tests
✓ Database migration tests
✓ Authentication flow tests
Frontend Tests:
✓ Component tests (Jest/Vitest)
✓ User flow tests
✓ API integration tests
✓ Visual regression tests (optional)
End-to-End Tests:
✓ Complete user registration → login → action
✓ Workflow trigger → execution → completion
✓ Video upload → AI processing → annotation display
✓ Reputation calculation → badge award
5.2 Performance Testing
# Load test each backend
# Install: pip install locust
# locustfile.py
from locust import HttpUser, task, between
class MBTQUser(HttpUser):
wait_time = between(1, 3)
host = "http://api.mbtq.local"
@task
def health_check(self):
self.client.get("/auth/health")
@task
def login(self):
self.client.post("/auth/login", json={
"email": "test@example.com",
"password": "password123"
})
# Run: locust -f locustfile.py
Phase 6: Documentation (Week 15)

6.1 API Documentation
Auto-generated from FastAPI:
DeafAUTH: http://auth.mbtq.local/docs
PinkSync: http://sync.mbtq.local/docs
Fibonrose: http://trust.mbtq.local/docs
Magicians: http://ai.mbtq.local/docs
Content: http://media.mbtq.local/docs

6.2 Architecture Documentation
docs/
├── architecture/
│ ├── overview.md
│ ├── backend-services.md
│ ├── api-design.md
│ └── database-schema.md
├── deployment/
│ ├── local-setup.md
│ ├── google-cloud-migration.md
│ └── dns-configuration.md
└── api/
└── (auto-generated from FastAPI)

Phase 7: Pre-Cloud Checklist
Before migrating to Google Cloud:
✓ All 5 backends running locally without errors
✓ Frontend connects to all backend APIs successfully
✓ Authentication flow works end-to-end
✓ Database migrations are reversible
✓ All tests passing (unit + integration + e2e)
✓ Performance acceptable (< 200ms API response)
✓ Error handling implemented everywhere
✓ Logging configured properly
✓ Security review completed
✓ Documentation up to date
✓ Environment variables documented
✓ Secrets management strategy defined
✓ Backup strategy defined
✓ Monitoring plan created
✓ Rollback procedure documented

Timeline Summary
Week 1-2: Foundation (structure, database, environment)
Week 3-6: Backend Development (5 services)
Week 7-10: Frontend Development
Week 11-12: API Integration & NGINX setup
Week 13-14: Testing & Validation
Week 15: Documentation
Week 16: Final review & pre-cloud prep
Total: ~4 months to production-ready local build
Daily Workflow During Build
# Morning
cd ~/mbtq
docker-compose up -d postgres redis # Start databases
./start-backends.sh # Start all 5 backends
cd frontend && npm run dev # Start frontend
cd mission-control && python main.py # Start dashboard
# Check everything is running
open http://control.mbtq.local
# Work on specific backend
cd backends/deafauth
# Make changes
# Tests auto-run on save (if using pytest-watch)
# Evening
git add .
git commit -m "feat: implemented user registration"
git push origin develop
docker-compose down # Stop everything
Cloud Migration (Phase 8 - Later)
When everything works perfectly locally:

1. Create Google Cloud project
2. Set up Cloud Run services (one per backend)
3. Set up Cloud SQL (PostgreSQL)
4. Set up Cloud Memorystore (Redis)
5. Deploy backends to Cloud Run
6. Deploy frontend to Cloud Run or Cloud Storage + CDN
7. Update DNS A/AAAA records to point to Google
8. Test in production
9. Monitor and iterate
But don’t think about this yet. Build locally first.
Current Focus

1. Run the audit script on Ubuntu machine
2. Clean up old directories
3. Create the MBTQ directory structure
4. Set up environment files
5. Install PostgreSQL + Redis locally


1. Build DeafAUTH backend (authentication)
2. Create Mission Control dashboard
3. Test local deployment
Don’t worry about cloud yet. Build it right locally first.