bruno/dss
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Initial commit: Clean DSS implementation

Browse Source 
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm

Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)

Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability

Migration completed: $(date)
🤖 Clean migration with full functionality preserved
This commit is contained in:
Digital Production Factory
2025-12-09 18:45:48 -03:00
commit 276ed71f31
884 changed files with 373737 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

299
SERVER_ARCHITECTURE_ANALYSIS.md Normal file
View File

@@ -0,0 +1,299 @@
# 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