dss/admin-ui/BACKEND_API_REQUIREMENTS.md

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:

[
  {
    "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:

{
  "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:

{
  "projectId": "project-id",
  "testCommand": "npm test"
}

Response:

{
  "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:

{
  "projectId": "project-id",
  "baselineUrl": "https://baseline.example.com",
  "compareUrl": "https://current.example.com"
}

Response:

{
  "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:

{
  "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:

{
  "projectId": "project-id",
  "flowName": "User Onboarding"
}

Response:

{
  "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:

{
  "projectId": "project-id",
  "fileKey": "abc123def456",
  "format": "svg|png|jpg"
}

Response:

{
  "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:

{
  "projectId": "project-id",
  "fileKey": "abc123def456",
  "format": "json|react"
}

Response:

{
  "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:

{
  "projectId": "project-id",
  "figmaUrl": "https://figma.com/...",
  "liveUrl": "https://app.example.com/..."
}

Response:

{
  "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:

{
  "projectId": "project-id",
  "content": "# ESRE markdown content..."
}

Response:

{
  "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):

   @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