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