FE FSD (Front End Full Stack Development) API Documentation

Base URL: /api/modules/{module_id}/functions/{function_id}

1. Generate FSD
Endpoint: POST /generate
Example: POST http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/generate
Description: Generates Frontend System Design (FSD) document using Claude AI
Request Body:
{
    "created_by": string,           // User requesting FSD generationx
    "custom_instructions": string   // Optional custom instructions for FSD generation
}
Success Response:
{
    "status": "success",
    "message": "FSD generated successfully",
    "data": {
        "fsd": {
            "ID": "FSD_12345678",
            "screen_id": "SCR_12345678",
            "content": {
                "overview": string,
                "ascii_design": string,
                "sections": [
                    {
                        "title": string,
                        "content": string,
                        "order": number
                    }
                ],
                "references": object
            },
            "type": "AI_GENERATED",
            "status": "NON_GENERATED",
            "version": "1.0.0",
            "version_number": 1,
            "function_id": "func_c5a8e0c6",
            "module_id": "MOD-40",
            "function_version": 1,
            "audit": {
                "created_by": string,
                "created_at": "2024-01-20T10:30:00Z",
                "updated_by": string,
                "updated_at": "2024-01-20T10:30:00Z",
                "status_changed_by": string,
                "status_changed_at": "2024-01-20T10:30:00Z"
            }
        },
        "metadata": {
            "input_tokens": number,
            "output_tokens": number,
            "parser_warnings": array,
            "raw_response": string,
            "claude_interaction": {
                "raw_prompt": string,
                "raw_response": string,
                "corrected_response": object
            }
        },
        "output_fsd": string
    }
}

2. List FSDs
Endpoint: GET /list
Example: GET http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/list
Description: List all FSDs for a module/function
Success Response:
{
    "status": "success",
    "message": "FSDs retrieved successfully",
    "data": {
        "fsds": [
            {
                "ID": "FSD_12345678",
                "screen_id": "SCR_12345678",
                "content": object,
                "type": string,
                "status": string,
                "version": string,
                "version_number": number,
                "function_id": string,
                "module_id": string,
                "function_version": number,
                "audit": object
            }
        ],
        "output_fsd": object
    }
}

3. Update FSD
Endpoint: PUT /{screen_id}/fsd/{fsd_id}
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/SCR_12345678/fsd/FSD_12345678
Description: Update an existing FSD
Request Body:
{
    "updated_by": string,      // User updating the FSD
    "output_fsd": string      // Updated FSD content as text
}
Success Response:
{
    "status": "success",
    "message": "FSD updated successfully",
    "data": {
        "fsd": {
            // Updated FSD object
        },
        "output_fsd": string
    }
}

4. Create FSD Version
Endpoint: POST /version/{screen_id}
Example: POST http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/version/SCR_12345678
Description: Create a new version of an FSD
Request Body:
{
    "created_by": string,     // User creating the version
    "comment": string        // Optional comment about this version
}
Success Response:
{
    "status": "success",
    "message": "FSD version created successfully",
    "data": {
        "version": {
            "ID": "FSDV_12345678",
            "fsd_id": "FSD_12345678",
            "module_id": string,
            "screen_id": string,
            "function_id": string,
            "version": string,
            "version_number": number,
            "function_version": number,
            "content": object,
            "created_by": string,
            "created_at": string,
            "comment": string,
            "is_current": boolean,
            "metadata": object,
            "output_fsd": string
        }
    }
}

5. List FSD Versions
Endpoint: GET /versions/{screen_id}
Example: GET http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/versions/SCR_12345678
Description: List all versions of an FSD
Success Response:
{
    "status": "success",
    "message": "FSD versions retrieved successfully",
    "data": {
        "total": number,
        "versions": [
            // Array of version objects
        ]
    }
}

6. Create Manual FSD
Endpoint: POST /{screen_id}/manual/create
Example: POST http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/SCR_12345678/manual/create
Description: Create a new FSD manually
Request Body:
{
    "title": string,           // Title of the FSD
    "description": string,     // Description of the FSD
    "created_by": string,      // User creating the FSD
    "output_fsd": string      // FSD content
}
Success Response:
{
    "status": "success",
    "message": "FSD created successfully",
    "data": {
        "fsd": {
            // FSD object
        },
        "output_fsd": string
    }
}

7. Activate FSD
Endpoint: PUT /{screen_id}/activate
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/SCR_12345678/activate
Description: Activate an FSD
Request Body:
{
    "updated_by": string      // User activating the FSD
}
Success Response:
{
    "status": "success",
    "message": "FSD activated successfully",
    "data": {
        "screen_id": string,
        "status": "ACTIVE",
        "updated_by": string,
        "updated_at": string
    }
}

8. Deactivate FSD
Endpoint: PUT /{screen_id}/deactivate
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/SCR_12345678/deactivate
Description: Deactivate an FSD
Request Body:
{
    "updated_by": string      // User deactivating the FSD
}
Success Response:
{
    "status": "success",
    "message": "FSD deactivated successfully",
    "data": {
        "screen_id": string,
        "status": "INACTIVE",
        "updated_by": string,
        "updated_at": string
    }
}

9. Restore FSD Version
Endpoint: POST /restore/{screen_id}/{version_id}
Example: POST http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/restore/SCR_12345678/FSDV_12345678
Description: Restore an FSD to a specific version
Success Response:
{
    "status": "success",
    "message": "FSD version restored successfully",
    "data": {
        "fsd": {
            // Restored FSD object
        },
        "output_fsd": string
    }
}

10. Mark for Development
Endpoint: PUT /{screen_id}/development
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/SCR_12345678/development
Description: Mark an FSD for development use and track its development status
Request Body:
{
    "version": string,        // Development version
    "status": string,        // Development status
    "notes": string         // Optional development notes
}
Success Response:
{
    "status": "success",
    "message": "FSD marked for development successfully",
    "data": {
        "fsd": {
            // Updated FSD object
        },
        "development_info": {
            "version": string,
            "status": string,
            "notes": string
        },
        "output_fsd": string
    }
}

11. Select FSD
Endpoint: PUT /{screen_id}/fsd/{fsd_id}/select
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/fe-fsd/SCR_12345678/fsd/FSD_12345678/select
Description: Select an FSD (deselects all others)
Success Response:
{
    "status": "success",
    "message": "FSD selected successfully",
    "data": {
        "screen_id": string,
        "fsd_id": string,
        "selected": true,
        "updated_at": string
    }
}

12. Deselect FSD
Endpoint: PUT /{screen_id}/fsd/{fsd_id}/deselect
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/fe-fsd/SCR_12345678/fsd/FSD_12345678/deselect
Description: Deselect an FSD
Success Response:
{
    "status": "success",
    "message": "FSD deselected successfully",
    "data": {
        "screen_id": string,
        "fsd_id": string,
        "selected": false,
        "updated_at": string
    }
}

Error Responses (Common for all endpoints):

1. Not Found (404):
{
    "detail": "Module not found"
}
{
    "detail": "FSD not found"
}
{
    "detail": "FSD version not found"
}

2. Bad Request (400):
{
    "detail": "No screen selected for FSD generation"
}
{
    "detail": "No mermaid diagram selected for FSD generation"
}

3. Internal Server Error (500):
{
    "detail": "Failed to save FSD"
}
{
    "detail": "Failed to create version"
}
{
    "detail": "Failed to update FSD"
}
{
    "detail": "Error generating FSD: {specific error message}"
}

Common Response Headers:
- Access-Control-Allow-Origin: *
- Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
- Access-Control-Allow-Headers: *
- Content-Type: application/json

Models:

FSD Document:
{
    "ID": string,                // Unique identifier (format: FSD_[8 hex chars])
    "screen_id": string,         // Associated screen ID
    "content": {
        "overview": string,
        "ascii_design": string,
        "sections": [
            {
                "title": string,
                "content": string,
                "order": number
            }
        ],
        "references": object
    },
    "type": string,              // "AI_GENERATED" or "MANUAL"
    "status": string,            // "ACTIVE", "INACTIVE", "NON_GENERATED"
    "version": string,           // Semantic version (e.g., "1.0.0")
    "version_number": number,    // Integer version number
    "function_id": string,       // Associated function ID
    "module_id": string,         // Associated module ID
    "function_version": number,  // Function version number
    "audit": {
        "created_by": string,
        "created_at": string,    // ISO 8601 timestamp
        "updated_by": string,
        "updated_at": string,    // ISO 8601 timestamp
        "status_changed_by": string,
        "status_changed_at": string
    }
}

Version Document:
{
    "ID": string,               // Unique version ID (format: FSDV_[8 hex chars])
    "fsd_id": string,           // Associated FSD ID
    "module_id": string,        // Associated module ID
    "screen_id": string,        // Associated screen ID
    "function_id": string,      // Associated function ID
    "version": string,          // Semantic version
    "version_number": number,   // Integer version number
    "function_version": number, // Function version number
    "content": object,          // FSD content object
    "created_by": string,       // Creator identifier
    "created_at": string,       // ISO 8601 timestamp
    "comment": string,          // Optional version comment
    "is_current": boolean,      // Whether this is the current version
    "metadata": {
        "input_tokens": number,
        "output_tokens": number,
        "parser_warnings": array,
        "claude_interaction": object
    },
    "output_fsd": string       // Raw FSD content
}

Notes:
- All timestamps are in ISO 8601 format
- IDs follow specific patterns:
  * FSD IDs: "FSD_" + 8 hex characters
  * Version IDs: "FSDV_" + 8 hex characters
  * Screen IDs: "SCR_" + 8 hex characters
- The content object structure is consistent across all FSD documents
- Error responses always include a "detail" field with the error message
- All endpoints support CORS with OPTIONS preflight
- Development tracking helps manage FSD lifecycle
- Version control maintains history of all changes
- Selection status is mutually exclusive within a function