Initial commit: Clean DSS implementation
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
350
admin-ui/BACKEND_API_REQUIREMENTS.md
Normal file
350
admin-ui/BACKEND_API_REQUIREMENTS.md
Normal file
@@ -0,0 +1,350 @@
|
||||
# Backend API Requirements for MVP1
|
||||
|
||||
This document lists all backend API endpoints required by the admin-ui components. These endpoints need to be implemented in the FastAPI backend (`/tools/api/server.py`).
|
||||
|
||||
## Status: Missing Endpoints
|
||||
|
||||
The following endpoints are called by frontend components but not yet implemented in the backend:
|
||||
|
||||
---
|
||||
|
||||
## 1. Projects API
|
||||
|
||||
### GET `/api/projects`
|
||||
**Used by:** `ds-project-selector.js`
|
||||
**Purpose:** Fetch list of all available projects
|
||||
**Request:** None
|
||||
**Response:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "project-id",
|
||||
"name": "Project Name",
|
||||
"description": "Project description",
|
||||
"storybook_url": "https://storybook.example.com",
|
||||
"figma_ui_file": "https://figma.com/file/abc123",
|
||||
"figma_ux_file": "https://figma.com/file/def456",
|
||||
"figma_qa_file": "https://figma.com/file/ghi789",
|
||||
"live_url": "https://app.example.com",
|
||||
"git_repo": "https://github.com/org/repo",
|
||||
"esre": "# ESRE content..."
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### GET `/api/projects/{project_id}`
|
||||
**Used by:** Multiple comparison tools
|
||||
**Purpose:** Fetch single project configuration
|
||||
**Request:** Path parameter `project_id`
|
||||
**Response:** Same as single project object above
|
||||
|
||||
### GET `/api/projects/{project_id}/esre`
|
||||
**Used by:** `ds-esre-editor.js`
|
||||
**Purpose:** Fetch ESRE (style requirements) for project
|
||||
**Request:** Path parameter `project_id`
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"content": "# ESRE markdown content..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Test Runner API
|
||||
|
||||
### POST `/api/test/run`
|
||||
**Used by:** `ds-test-results.js`
|
||||
**Purpose:** Execute npm test command and return parsed results
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"projectId": "project-id",
|
||||
"testCommand": "npm test"
|
||||
}
|
||||
```
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"summary": {
|
||||
"total": 45,
|
||||
"passed": 42,
|
||||
"failed": 2,
|
||||
"skipped": 1,
|
||||
"duration": 2.341
|
||||
},
|
||||
"suites": [
|
||||
{
|
||||
"name": "Suite Name",
|
||||
"tests": [
|
||||
{
|
||||
"name": "test description",
|
||||
"status": "passed|failed|skipped",
|
||||
"duration": 0.123,
|
||||
"error": "error message if failed"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"coverage": {
|
||||
"lines": 85,
|
||||
"functions": 90,
|
||||
"branches": 75,
|
||||
"statements": 85
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Regression Testing API
|
||||
|
||||
### POST `/api/regression/run`
|
||||
**Used by:** `ds-regression-testing.js`
|
||||
**Purpose:** Run visual regression tests between baseline and current
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"projectId": "project-id",
|
||||
"baselineUrl": "https://baseline.example.com",
|
||||
"compareUrl": "https://current.example.com"
|
||||
}
|
||||
```
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"summary": {
|
||||
"passed": 15,
|
||||
"failed": 3,
|
||||
"total": 18
|
||||
},
|
||||
"diffs": [
|
||||
{
|
||||
"component": "Button",
|
||||
"hasDifference": true,
|
||||
"diffPercentage": 2.5,
|
||||
"baselineImage": "/screenshots/baseline/button.png",
|
||||
"currentImage": "/screenshots/current/button.png",
|
||||
"diffImage": "/screenshots/diff/button.png"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Assets API
|
||||
|
||||
### GET `/api/assets/list`
|
||||
**Used by:** `ds-asset-list.js`
|
||||
**Purpose:** List all design assets (icons, images) for project
|
||||
**Request:** Query parameter `projectId`
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"assets": [
|
||||
{
|
||||
"id": "asset-1",
|
||||
"name": "icon-home.svg",
|
||||
"type": "icon",
|
||||
"url": "/assets/icons/home.svg",
|
||||
"thumbnailUrl": "/assets/thumbs/home.png",
|
||||
"size": "2.3 KB"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Navigation Demos API
|
||||
|
||||
### POST `/api/navigation/generate`
|
||||
**Used by:** `ds-navigation-demos.js`
|
||||
**Purpose:** Generate HTML navigation flow demos
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"projectId": "project-id",
|
||||
"flowName": "User Onboarding"
|
||||
}
|
||||
```
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"url": "/demos/user-onboarding.html",
|
||||
"thumbnailUrl": "/demos/thumbs/user-onboarding.png"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Figma Export API
|
||||
|
||||
### POST `/api/figma/export-assets`
|
||||
**Used by:** `ds-figma-plugin.js`
|
||||
**Purpose:** Export assets from Figma file
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"projectId": "project-id",
|
||||
"fileKey": "abc123def456",
|
||||
"format": "svg|png|jpg"
|
||||
}
|
||||
```
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"count": 25,
|
||||
"assets": {
|
||||
"icon-home": "/exports/icon-home.svg",
|
||||
"icon-user": "/exports/icon-user.svg"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### POST `/api/figma/export-components`
|
||||
**Used by:** `ds-figma-plugin.js`
|
||||
**Purpose:** Export component definitions from Figma
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"projectId": "project-id",
|
||||
"fileKey": "abc123def456",
|
||||
"format": "json|react"
|
||||
}
|
||||
```
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"count": 12,
|
||||
"components": {
|
||||
"Button": {
|
||||
"variants": ["primary", "secondary"],
|
||||
"props": ["size", "disabled"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. QA Screenshot API
|
||||
|
||||
### POST `/api/qa/screenshot-compare`
|
||||
**Used by:** `ds-figma-live-compare.js`
|
||||
**Purpose:** Take screenshots of Figma and live for comparison
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"projectId": "project-id",
|
||||
"figmaUrl": "https://figma.com/...",
|
||||
"liveUrl": "https://app.example.com/..."
|
||||
}
|
||||
```
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"figmaScreenshot": "/screenshots/figma-123.png",
|
||||
"liveScreenshot": "/screenshots/live-123.png"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. ESRE Save API
|
||||
|
||||
### POST `/api/esre/save`
|
||||
**Used by:** `ds-esre-editor.js`
|
||||
**Purpose:** Save ESRE (style requirements) content
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"projectId": "project-id",
|
||||
"content": "# ESRE markdown content..."
|
||||
}
|
||||
```
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"savedAt": "2025-01-15T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Priority Order
|
||||
1. **Critical (Blocking MVP1):**
|
||||
- `/api/projects` - Required for project selection
|
||||
- `/api/projects/{id}` - Required for tool configuration
|
||||
|
||||
2. **High Priority (Core Features):**
|
||||
- `/api/test/run` - Test results viewer
|
||||
- `/api/esre/save` - ESRE editor
|
||||
|
||||
3. **Medium Priority (Team Tools):**
|
||||
- `/api/regression/run` - Visual regression testing
|
||||
- `/api/figma/export-assets` - Figma asset export
|
||||
- `/api/figma/export-components` - Figma component export
|
||||
|
||||
4. **Low Priority (Nice to Have):**
|
||||
- `/api/assets/list` - Asset list viewer
|
||||
- `/api/navigation/generate` - Navigation demos
|
||||
- `/api/qa/screenshot-compare` - QA screenshots
|
||||
|
||||
### Implementation Strategy
|
||||
|
||||
1. **Add to FastAPI server** (`/tools/api/server.py`):
|
||||
```python
|
||||
@app.get("/api/projects")
|
||||
async def list_projects():
|
||||
# Implementation
|
||||
pass
|
||||
```
|
||||
|
||||
2. **Use existing MCP tools where possible:**
|
||||
- Token extraction → `dss_extract_tokens`
|
||||
- Project analysis → `dss_analyze_project`
|
||||
- Component audit → `dss_audit_components`
|
||||
|
||||
3. **Add project configuration storage:**
|
||||
- Use JSON files in `/projects/{id}/config.json`
|
||||
- Or use SQLite database for persistence
|
||||
|
||||
4. **Implement test runner:**
|
||||
- Use `subprocess` to execute `npm test`
|
||||
- Parse Jest/test output
|
||||
- Return structured results
|
||||
|
||||
### Fallback Strategy
|
||||
|
||||
For MVP1 release, if backend endpoints are not ready:
|
||||
- Components will show empty states with helpful error messages
|
||||
- localStorage caching will preserve user data
|
||||
- All components gracefully handle missing endpoints
|
||||
- Project selector falls back to hardcoded 'admin-ui' project
|
||||
|
||||
---
|
||||
|
||||
## Current Status
|
||||
|
||||
✅ **Implemented:**
|
||||
- MCP tool execution via `/api/mcp/tools/{tool_name}/execute`
|
||||
- All DSS MCP tools (tokens, analysis, audit, etc.)
|
||||
- Browser automation tools via plugin
|
||||
|
||||
❌ **Missing:**
|
||||
- All 8 endpoint groups listed above
|
||||
- Project CRUD operations
|
||||
- Test runner integration
|
||||
- Asset management
|
||||
- ESRE persistence
|
||||
|
||||
**Estimated Implementation Time:** 4-6 hours for all endpoints
|
||||
|
||||
---
|
||||
|
||||
Last updated: 2025-01-15
|
||||
Reference in New Issue
Block a user