dss/SERVER_ARCHITECTURE_ANALYSIS.md

DSS Server Architecture Analysis

Date: 2025-12-07 Issue: 502 Bad Gateway on https://dss.overbits.luz.uy/ Status: ✅ RESOLVED

Problem Analysis

Initial Issue

• URL https://dss.overbits.luz.uy/ returned 502 Bad Gateway
• Nginx was configured to proxy to 127.0.0.1:3456
• Nothing was listening on port 3456

Confusion Points

1. Two FastAPI servers found in codebase
2. Vite dev server recently introduced
3. Unclear which server should run in production

Architecture Investigation

Complete Server Stack

┌─────────────────────────────────────────────────────┐
│          https://dss.overbits.luz.uy/                │
│                                                       │
│  Nginx (Port 443) with Basic Auth                   │
│  - SSL certificates via Let's Encrypt                │
│  - auth_basic: "DSS Restricted"                      │
│  - Proxies to: http://127.0.0.1:3456                │
└─────────────────────┬───────────────────────────────┘
                      │
                      │ reverse proxy
                      │
┌─────────────────────▼───────────────────────────────┐
│          FastAPI Server (Port 3456)                  │
│  Location: tools/api/server.py                       │
│                                                       │
│  Serves:                                             │
│  - REST API endpoints (/api/*)                       │
│  - Static files from admin-ui/ directory             │
│  - Browser logger endpoint (/api/browser-logs)       │
│                                                       │
│  Mount points:                                       │
│  - /admin-ui → StaticFiles(admin-ui/)               │
│  - / → StaticFiles(admin-ui/)                       │
└──────────────────────────────────────────────────────┘

Server Files Found

File Path	Purpose	Status
/home/overbits/dss/tools/api/server.py	Production FastAPI	✅ Active
/home/overbits/dss/cli/python/api/server.py	CLI/Development version	Inactive
/home/overbits/dss/servers/visual-qa/dist/index.js	Legacy Node.js server	Deprecated

Startup Configuration

Systemd Services

1. dss-api.service (tools/api/dss-api.service)

   • Target: tools/api/server.py
   • Port: 3456
   • Status: Was inactive (now running manually)
   • Path: /home/overbits/dss/tools/api/dss-api.service

2. dss-mcp.service

   • MCP server for AI agents
   • Separate from web server

3. dss.service (infra/dss.service)

   • Legacy Node.js server
   • No longer used

Manual Startup Scripts

• start-ui.sh: Runs FastAPI with uvicorn

  cd tools/api && python -m uvicorn server:app --host 0.0.0.0 --port 3456 --reload
  

Admin UI Architecture

Development vs Production

Mode	Server	Port	Purpose
Development	Vite (npm run dev)	3456	Hot Module Reload, rapid iteration
Production	FastAPI (tools/api/server.py)	3456	Serves API + static files

Why Vite Was Introduced

• Development Benefits:

  • Instant Hot Module Reload (HMR)
  • Faster than full server restart
  • Better DX for frontend work

• Not Used in Production:

  • Vite is dev-only (configured in vite.config.js)
  • FastAPI serves the static admin-ui files directly
  • No build step required (FastAPI mounts source directory)

Admin UI File Structure

admin-ui/
├── index.html              # Main entry point
├── css/                    # Layered CSS architecture
│   ├── dss-core.css       # Layer 0: Reset, grid
│   ├── dss-tokens.css     # Layer 1: Design tokens
│   ├── dss-theme.css      # Layer 2: Semantic theme
│   └── dss-components.css # Layer 3: Components
├── js/                     # JavaScript modules
│   ├── core/
│   │   └── browser-logger.js  # Logs → /api/browser-logs
│   ├── services/
│   └── components/
├── dist/                   # Build output (optional)
└── vite.config.js         # Vite dev server config

Static File Mounting

FastAPI Configuration (tools/api/server.py):

UI_DIR = Path(__file__).parent.parent.parent / "admin-ui"
if UI_DIR.exists():
    app.mount("/admin-ui", StaticFiles(directory=str(UI_DIR), html=True), name="admin-ui")

# Catch-all at the end
app.mount("/", StaticFiles(directory=str(UI_DIR), html=True), name="ui")

Key Points:

• FastAPI mounts the admin-ui/ source directory
• NOT the dist/ build directory
• Static files served directly without build step
• API routes take precedence over static files

Browser Integration

Browser Logger Architecture

Client-Side (admin-ui/js/core/browser-logger.js):

• Captures: console, errors, network, performance, Web Vitals
• Auto-syncs every 30 seconds
• Endpoint: POST /api/browser-logs
• Shadow State snapshots for remote monitoring

Server-Side (tools/api/server.py):

• Receives browser logs via REST API
• Stores in SQLite database
• Enables remote debugging of admin UI

Developer Tools Integration

• Playwright browser automation (optional)
• Chrome DevTools Protocol support
• Headless log analyzer for CI/CD
• All communicate via FastAPI REST endpoints

Resolution

What Was Done

1. Identified correct production server: tools/api/server.py
2. Confirmed FastAPI was not running on port 3456
3. Started FastAPI server manually:

   cd /home/overbits/dss/tools/api
   python3 -m uvicorn server:app --host 127.0.0.1 --port 3456
   

Current Status

✅ FastAPI Server Running:

INFO:     Uvicorn running on http://127.0.0.1:3456
INFO:     Application startup complete.

✅ Database Initialized:

[Storage] Database initialized at /home/overbits/dss/.dss/dss.db

✅ Site Accessible:

• 502 Bad Gateway → 401 Authorization Required (correct behavior with nginx auth_basic)
• Server responding: HTTP/1.1 200 OK (when auth provided)

Recommendations

1. Enable Systemd Service

For automatic startup on reboot:

# Copy service file to systemd
sudo cp /home/overbits/dss/tools/api/dss-api.service /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

# Enable and start service
sudo systemctl enable dss-api.service
sudo systemctl start dss-api.service

# Check status
sudo systemctl status dss-api.service

2. Process Management

Alternatively, use a process manager like PM2 or supervisord:

# Using PM2 (if installed)
pm2 start /home/overbits/dss/start-ui.sh --name dss-api
pm2 save
pm2 startup

3. Monitoring

Monitor the FastAPI server:

# Check if running
lsof -i :3456

# View logs
journalctl -u dss-api.service -f

# Or check application logs
tail -f /home/overbits/dss/.dss/logs/dss-api.log

4. Development Workflow

For frontend development:

# Option A: Use Vite dev server (HMR enabled)
cd admin-ui
npm run dev

# Option B: Use FastAPI with --reload (auto-restart on changes)
cd tools/api
python3 -m uvicorn server:app --host 127.0.0.1 --port 3456 --reload

5. Production Deployment

Current setup is production-ready:

• ✅ FastAPI serves both API and static files
• ✅ Nginx provides SSL and basic auth
• ✅ Database initialized
• ⚠️ Consider enabling systemd service for auto-restart

Technical Details

Port Configuration

• 3456: FastAPI server (API + static files)
• 6006: Storybook (optional component library)
• 3457: MCP server (AI agent communication)

Environment Variables

FastAPI loads .env from:

1. dss-mvp1/.env (primary)
2. /.env (root fallback)
3. tools/api/.env (local fallback)

Database

• Location: .dss/dss.db (SQLite)
• Tables: Projects, Components, SyncHistory, ActivityLog, Teams, Cache, etc.
• Initialized on first startup

Security

• Nginx Basic Auth: Protects entire site
• HTTPS: Let's Encrypt SSL certificates
• CORS: Configured in FastAPI
• File Access: Sandboxed via SandboxedFS

Summary

Root Cause: FastAPI server was not running on port 3456

Solution: Started FastAPI server manually

Architecture: FastAPI serves both REST API and static admin-ui files. Vite is for development only (HMR). Nginx provides SSL termination and basic authentication.

Status: ✅ Production server now operational

Next Steps:

1. Enable systemd service for automatic startup
2. Consider process monitoring (PM2/supervisord)
3. Set up log rotation
4. Configure firewall rules if needed

---

Document Generated: 2025-12-07 Server PID: 3366802 Uptime: Since 21:08:25 GMT