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
  ```bash
  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):
```python
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:
   ```bash
   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:

```bash
# 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**:

```bash
# 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:
```bash
# 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:
```bash
# 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