dss/API_SPECIFICATION_IMMUTABLE.md

Design System Swarm - API Specification (IMMUTABLE)

Document Version: 1.0-IMMUTABLE Created: 2025-12-08 Status: Immutable Reference Document Lock Date: 2025-12-08 Authority: Project Technical Specification

---

🔒 IMMUTABILITY NOTICE

This document defines the complete API specification for the Design System Swarm platform. Once committed, this specification becomes the source of truth and should not be modified without version bump and full audit trail.

All changes to this specification MUST:

1. Create new version (e.g., 1.1-IMMUTABLE)
2. Document reason for change in changelog
3. Include migration path for existing consumers
4. Be reviewed and approved by technical lead
5. Trigger client library updates

---

API OVERVIEW

API Base URL: https://dss.overbits.luz.uy/api (Production) Development Base URL: http://localhost:3001/api API Version: 1.0 Response Format: JSON Authentication: JWT Bearer Token Rate Limit: 100 requests per 15 minutes per user

---

AUTHENTICATION

Login Endpoint

POST /auth/login
Content-Type: application/json

Request:
{
  "email": "user@example.com",
  "password": "password"
}

Response (200):
{
  "status": "success",
  "code": "LOGIN_SUCCESS",
  "message": "Login successful",
  "data": {
    "user": {
      "id": "uuid",
      "email": "user@example.com",
      "name": "User Name",
      "role": "admin|editor|viewer"
    },
    "tokens": {
      "accessToken": "jwt_token",
      "refreshToken": "jwt_token"
    }
  }
}

Authorization Header

Authorization: Bearer <accessToken>

Token expiry: 1 hour (3600 seconds) Refresh token expiry: 30 days

---

STANDARD RESPONSE FORMAT

Success Response

{
  "status": "success",
  "code": "OPERATION_CODE",
  "message": "Human readable description",
  "data": {
    // Response-specific data
  }
}

HTTP Status: 200, 201, 202, 204

Error Response

{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "Error description",
  "data": null
}

HTTP Status: 400, 401, 403, 404, 409, 500, 503

---

HTTP STATUS CODES

Code	Meaning	Use Case
200	OK	Successful GET/PUT request
201	Created	Resource created successfully (POST)
202	Accepted	Async operation queued
204	No Content	Successful DELETE
400	Bad Request	Invalid input/validation error
401	Unauthorized	Missing or invalid JWT token
403	Forbidden	Valid token but insufficient permissions
404	Not Found	Resource does not exist
409	Conflict	Resource already exists (duplicate)
500	Internal Server Error	Unexpected server error
503	Service Unavailable	Server at capacity/maintenance

---

PHASE 1 ENDPOINTS (IMMUTABLE)

Configuration

GET /config
Auth: None
Response: 200 OK
{
  "status": "success",
  "code": "CONFIG_RETRIEVED",
  "data": {
    "app": { "name": "Design System Swarm", "version": "1.0.0" },
    "features": { /* feature flags */ }
  }
}

Server Logging

POST /logs
Auth: JWT (Required)
Request: { "level": "log|warn|error|info|debug", "message": "string", "context": {} }
Response: 201 Created
{
  "status": "success",
  "code": "LOG_CREATED",
  "data": { "logId": "uuid", "timestamp": "iso-string" }
}

Browser Logging

POST /logs/browser
Auth: JWT (Required)
Request: { "level": "string", "message": "string", "url": "string", "userAgent": "string" }
Response: 201 Created

Retrieve Logs

GET /logs?level=error&source=browser&limit=100&offset=0
Auth: JWT (Required)
Response: 200 OK
{
  "status": "success",
  "code": "LOGS_RETRIEVED",
  "data": {
    "total": 150,
    "limit": 100,
    "offset": 0,
    "logs": [{ "id": "uuid", "level": "string", "message": "string", "timestamp": "iso-string" }]
  }
}

---

PHASE 2 ENDPOINTS (IMMUTABLE)

Notifications (Server-Sent Events)

GET /notifications/events
Auth: JWT (Required)
Type: SSE (Server-Sent Events)
Response: 200 OK (persistent connection)

Events format:
data: {"type": "connection:established|notification", "timestamp": "iso-string", "data": {}}

Example notification:
data: {"type": "project:created", "timestamp": "2025-12-08T20:35:15.972Z", "data": {"projectId": "uuid"}}

Notification Statistics

GET /notifications/stats
Auth: JWT (Required, Admin only)
Response: 200 OK
{
  "status": "success",
  "code": "NOTIFICATION_STATS",
  "data": {
    "totalSubscribers": 5,
    "userCount": 3,
    "byUser": { "user-id": 2, "user-id-2": 1 }
  }
}

Test Notification

POST /notifications/test
Auth: JWT (Required)
Request: { "message": "string" }
Response: 200 OK
{
  "status": "success",
  "code": "TEST_NOTIFICATION_SENT",
  "data": { "timestamp": "iso-string" }
}

List MCP Tools

GET /mcp/tools
Auth: JWT (Required)
Response: 200 OK
{
  "status": "success",
  "code": "MCP_TOOLS_LIST",
  "data": {
    "tools": [
      {
        "name": "dss-analyze-project",
        "description": "Analyze codebase for design patterns",
        "params": { "projectPath": "string", "depth": "number" }
      }
    ]
  }
}

Execute MCP Tool

POST /mcp/tools/:name/execute
Auth: JWT (Required)
Request: { "projectPath": "string", "depth": 2 }
Response: 202 Accepted
{
  "status": "success",
  "code": "TOOL_EXECUTION_QUEUED",
  "data": { "estimatedDuration": "30-60 seconds" }
}

Discover Project

POST /mcp/discover_project
Auth: JWT (Required)
Request: { "projectId": "uuid", "path": "string", "depth": 2 }
Response: 202 Accepted
{
  "status": "success",
  "code": "DISCOVERY_QUEUED",
  "data": {
    "discoveryId": "string",
    "estimatedTime": "2-5 minutes",
    "pollEndpoint": "/api/discovery/activity"
  }
}

Get Quick Wins

POST /mcp/get_quick_wins
Auth: JWT (Required)
Request: { "projectId": "uuid", "path": "string" }
Response: 202 Accepted
{
  "status": "success",
  "code": "QUICK_WINS_ANALYSIS_QUEUED",
  "data": {
    "analysisId": "string",
    "expectedWins": ["string"],
    "estimatedTime": "1-3 minutes"
  }
}

Tool Callback (Webhook)

POST /mcp/callback
Auth: None
Request: { "toolName": "string", "status": "completed|failed", "data": {}, "projectId": "uuid" }
Response: 200 OK
{
  "status": "success",
  "code": "CALLBACK_ACKNOWLEDGED",
  "data": null
}

---

PHASE 3 ENDPOINTS (IMMUTABLE - DESIGNED, NOT YET IMPLEMENTED)

Team Operations

List Teams

GET /teams
Auth: JWT (Required)
Response: 200 OK
{
  "status": "success",
  "code": "TEAMS_RETRIEVED",
  "data": {
    "teams": [
      {
        "id": "uuid",
        "name": "Design System",
        "description": "string",
        "ownerId": "uuid",
        "settings": {}
      }
    ]
  }
}

Create Team

POST /teams
Auth: JWT (Required)
Request: { "name": "string (required)", "description": "string (optional)" }
Response: 201 Created
{
  "status": "success",
  "code": "TEAM_CREATED",
  "data": { "team": { "id": "uuid", "name": "string", "ownerId": "uuid" } }
}

Get Team

GET /teams/:id
Auth: JWT (Required, must be team member)
Response: 200 OK
{
  "status": "success",
  "code": "TEAM_RETRIEVED",
  "data": { "team": { /* team object */ } }
}

Update Team

PUT /teams/:id
Auth: JWT (Required, admin only)
Request: { "name": "string", "description": "string" }
Response: 200 OK
{
  "status": "success",
  "code": "TEAM_UPDATED",
  "data": { "team": { /* updated team */ } }
}

Delete Team

DELETE /teams/:id
Auth: JWT (Required, owner only)
Response: 200 OK
{
  "status": "success",
  "code": "TEAM_DELETED",
  "data": null
}

Team Member Management

List Members

GET /teams/:id/members
Auth: JWT (Required, team member)
Response: 200 OK
{
  "status": "success",
  "code": "TEAM_MEMBERS_RETRIEVED",
  "data": {
    "members": [
      {
        "id": "uuid",
        "teamId": "uuid",
        "userId": "uuid",
        "role": "admin|editor|viewer",
        "joinedAt": "iso-string"
      }
    ]
  }
}

Add Member

POST /teams/:id/members
Auth: JWT (Required, admin only)
Request: { "userId": "uuid (required)", "role": "viewer|editor|admin" }
Response: 201 Created
{
  "status": "success",
  "code": "MEMBER_ADDED",
  "data": { "member": { /* member object */ } }
}

Update Member Role

PUT /teams/:id/members/:memberId
Auth: JWT (Required, admin only)
Request: { "role": "admin|editor|viewer" }
Response: 200 OK
{
  "status": "success",
  "code": "MEMBER_UPDATED",
  "data": { "member": { /* updated member */ } }
}

Remove Member

DELETE /teams/:id/members/:memberId
Auth: JWT (Required, admin only)
Response: 200 OK
{
  "status": "success",
  "code": "MEMBER_REMOVED",
  "data": null
}

Team Settings

Get Settings

GET /teams/:id/settings
Auth: JWT (Required, team member)
Response: 200 OK
{
  "status": "success",
  "code": "TEAM_SETTINGS_RETRIEVED",
  "data": {
    "settings": {
      "teamId": "uuid",
      "allowMemberInvites": boolean,
      "requireApprovalForProjects": boolean,
      "defaultRole": "viewer",
      "features": {}
    }
  }
}

Update Settings

PUT /teams/:id/settings
Auth: JWT (Required, admin only)
Request: { "allowMemberInvites": boolean, "defaultRole": "string" }
Response: 200 OK
{
  "status": "success",
  "code": "TEAM_SETTINGS_UPDATED",
  "data": { "settings": { /* updated settings */ } }
}

Team Dashboard

Get Dashboard

GET /teams/:id/dashboard
Auth: JWT (Required, team member)
Response: 200 OK
{
  "status": "success",
  "code": "TEAM_DASHBOARD_RETRIEVED",
  "data": {
    "dashboard": {
      "teamId": "uuid",
      "memberCount": 5,
      "activeMembers": 4,
      "stats": {
        "projectsCreatedThisMonth": 3,
        "componentsCreatedThisMonth": 12,
        "tokensUpdatedThisMonth": 47
      },
      "recentActivity": []
    }
  }
}

---

PHASE 4 ENDPOINTS (IMMUTABLE - DESIGNED, NOT YET IMPLEMENTED)

Discovery & Analysis

Start Discovery Scan

POST /discovery/scan
Auth: JWT (Required)
Request: { "projectId": "uuid (required)", "type": "project-analysis|quick-wins|component-audit|token-extraction" }
Response: 202 Accepted
{
  "status": "success",
  "code": "DISCOVERY_SCAN_STARTED",
  "data": {
    "discoveryId": "uuid",
    "status": "queued",
    "estimatedTime": "2-5 minutes"
  }
}

Get Discovery Activity

GET /discovery/activity?projectId=uuid&limit=50&offset=0
Auth: JWT (Required)
Response: 200 OK
{
  "status": "success",
  "code": "DISCOVERY_ACTIVITY_RETRIEVED",
  "data": {
    "total": 100,
    "limit": 50,
    "offset": 0,
    "activities": [
      {
        "id": "uuid",
        "projectId": "uuid",
        "type": "project-analysis",
        "status": "completed",
        "progress": 100,
        "startedAt": "iso-string",
        "completedAt": "iso-string"
      }
    ]
  }
}

Get Discovery Statistics

GET /discovery/stats
Auth: JWT (Required)
Response: 200 OK
{
  "status": "success",
  "code": "DISCOVERY_STATS_RETRIEVED",
  "data": {
    "stats": {
      "total": 50,
      "byType": { "project-analysis": 30, "quick-wins": 15, "component-audit": 5 },
      "byStatus": { "completed": 45, "running": 3, "failed": 2 },
      "recentCompleted": { /* discovery object */ }
    }
  }
}

---

PHASE 5 ENDPOINTS (IMMUTABLE - ROADMAP)

5A: Figma Integration (9 endpoints)

1. GET /figma/health - API health check
2. POST /figma/extract-variables - Extract Figma variables
3. POST /figma/extract-components - Extract components
4. POST /figma/extract-styles - Extract design tokens
5. POST /figma/sync-tokens - Bidirectional sync
6. POST /figma/visual-diff - Visual comparison
7. POST /figma/validate-components - Validate compliance
8. POST /figma/generate-code - Generate code
9. POST /figma/export-assets - Export assets

5B: QA/Testing (2 endpoints)

1. POST /qa/screenshot-compare - Visual regression
2. POST /test/run - Execute tests

5C: Services (6+ endpoints)

1. POST /claude/chat - Claude AI chat
2. POST /ai/chat - Generic AI chat
3. POST /dss/save-tokens - Save design tokens
4. POST /navigation/generate - Generate navigation
5. POST /system/reset - Admin reset (DANGEROUS)
6. GET /assets/list - List design assets

---

ERROR CODES REFERENCE

Code	HTTP	Meaning
VALIDATION_ERROR	400	Invalid input validation
UNAUTHORIZED	401	Missing/invalid JWT
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource doesn't exist
DUPLICATE_KEY	409	Resource already exists
TEAM_NOT_FOUND	404	Team doesn't exist
MEMBER_NOT_FOUND	404	Team member doesn't exist
PROJECT_NOT_FOUND	404	Project doesn't exist
TOOL_NOT_FOUND	404	MCP tool not found
TOOL_EXECUTION_QUEUED	202	Tool queued successfully
DISCOVERY_QUEUED	202	Discovery queued
INTERNAL_SERVER_ERROR	500	Unexpected error
SERVICE_UNAVAILABLE	503	Server at capacity

---

ROLE-BASED ACCESS CONTROL (RBAC)

Role Definitions

• Admin - Full control, can manage team, members, settings
• Editor - Can create/edit projects, components, tokens
• Viewer - Read-only access, cannot modify anything

Permission Matrix

Action	Admin	Editor	Viewer
Create Team	✓	✗	✗
Update Team	✓	✗	✗
Delete Team	✓ (owner)	✗	✗
Manage Members	✓	✗	✗
Create Project	✓	✓	✗
Edit Project	✓	✓	✗
View Project	✓	✓	✓
Delete Project	✓	✓ (owner)	✗

---

VERSIONING & CHANGELOG

Version History

• 1.0-IMMUTABLE (2025-12-08) - Initial API specification
  • Phase 1-2: 12 endpoints implemented
  • Phase 3-4: 15 endpoints designed
  • Phase 5: 17+ endpoints planned

Change Process

All changes to this specification require:

1. Version number increment
2. Detailed change documentation
3. Migration guide for clients
4. Technical lead approval
5. Client notification period (minimum 30 days for breaking changes)

---

DEPLOYMENT CHECKLIST

Before Deploying

• All endpoints tested locally with curl
• Database migrations prepared and tested
• Error handling implemented for all cases
• RBAC verified on protected endpoints
• Rate limiting configured
• Logging configured
• Monitoring alerts set up

Rollback Plan

• Database rollback scripts prepared
• Code rollback procedure documented
• Backup of production data taken
• Team notified of deployment

Post-Deployment

• Verify all endpoints responding
• Monitor error logs
• Check performance metrics
• Verify database persistence
• Test RBAC in production

---

SUPPORT & DOCUMENTATION

API Documentation: This specification Implementation Guide: /PHASE_3_4_5_IMPLEMENTATION.md Error Handling: See ERROR CODES REFERENCE section Authentication: See AUTHENTICATION section Rate Limiting: 100 requests per 15 minutes per user

---

Status: 🔒 IMMUTABLE - DO NOT MODIFY WITHOUT VERSION BUMP Last Updated: 2025-12-08 Next Review: After Phase 3 implementation Maintained By: Technical Lead