ER Diagram API Documentation

Base URL: /api/modules/{module_id}/functions/{function_id}/er-diagrams

1. Generate ER Diagram
Endpoint: POST /generate
Example: POST http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/er-diagrams/generate
Description: Generates ER diagram using Claude AI
Request Body:
{
    "use_default_template": boolean,  // Whether to use default template
    "custom_instructions": string     // Required if use_default_template is false
}
Success Response:
{
    "message": "ER diagram generated successfully",
    "diagrams": [
        {
            "ID": "ERD_12345678",
            "title": "ER Diagram for Function Name",
            "description": "Generated ER diagram based on function analysis",
            "diagram": "erDiagram...",
            "raw": "raw diagram content",
            "function_id": "func_c5a8e0c6",
            "module_id": "MOD-40",
            "created_at": "2024-01-20T10:30:00Z",
            "updated_at": "2024-01-20T10:30:00Z",
            "created_by": "claude",
            "last_modified_by": "claude",
            "current_version": 1,
            "has_versions": true,
            "status": "active",
            "selected": false,
            "api_usage": {
                "type": "generated",
                "timestamp": "2024-01-20T10:30:00Z",
                "metrics": {
                    // API usage metrics
                }
            }
        }
    ],
    "metadata": {
        "function_id": "func_c5a8e0c6",
        "module_id": "MOD-40",
        "created_at": "2024-01-20T10:30:00Z",
        "updated_at": "2024-01-20T10:30:00Z",
        "api_usage": {
            // API usage metrics
        }
    }
}

2. Create ER Diagram Manually
Endpoint: POST /manual/create
Example: POST http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/er-diagrams/manual/create
Description: Create new ER diagram manually
Request Body:
{
    "title": string,           // ER diagram title
    "description": string,     // ER diagram description
    "diagram": string,         // ER diagram content
    "raw": string,            // Raw diagram content
    "created_by": string      // Creator identifier
}
Success Response:
{
    "message": "ER diagram created successfully",
    "diagram": {
        "ID": "ERD_12345678",
        "title": "Manual ER Diagram",
        "description": "Manually created ER diagram",
        "diagram": "erDiagram...",
        "raw": "raw diagram content",
        "function_id": "func_c5a8e0c6",
        "module_id": "MOD-40",
        "created_at": "2024-01-20T10:30:00Z",
        "updated_at": "2024-01-20T10:30:00Z",
        "created_by": "user123",
        "last_modified_by": "user123",
        "current_version": 1,
        "has_versions": true,
        "status": "active",
        "selected": false,
        "api_usage": {
            "type": "manual",
            "timestamp": "2024-01-20T10:30:00Z",
            "metrics": {
                "entities": 5,
                "relationships": 4,
                "attributes": 15,
                "complexity_score": 16.5
            },
            "validation": {
                "errors": [],
                "warnings": [
                    "Entity 'User' has no attributes defined"
                ]
            },
            "performance": {
                "generation_time_ms": 123.45,
                "memory_usage_mb": 0
            }
        }
    }
}

3. List All ER Diagrams
Endpoint: GET /list-erdiagrams
Example: GET http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/er-diagrams/list-erdiagrams
Description: List all ER diagrams for a module/function
Path Parameters:
- module_id (required): The ID of the module (e.g., MOD-40)
- function_id (required): The ID of the function (e.g., func_c5a8e0c6)
Success Response:
{
    "total": 2,
    "diagrams": [
        {
            "ID": "ERD_12345678",
            "title": "ER Diagram Title",
            "description": "ER diagram description",
            "diagram": "erDiagram...",
            "raw": "raw diagram content",
            "function_id": "func_c5a8e0c6",
            "module_id": "MOD-40",
            "created_at": "2024-01-20T10:30:00Z",
            "updated_at": "2024-01-20T10:30:00Z",
            "created_by": "user123",
            "last_modified_by": "user123",
            "current_version": 1,
            "has_versions": true,
            "status": "active",
            "selected": false,
            "api_usage": {
                "type": "manual",
                "timestamp": "2024-01-20T10:30:00Z",
                "metrics": {
                    "entities": 5,
                    "relationships": 4,
                    "attributes": 15,
                    "complexity_score": 16.5
                },
                "validation": {
                    "errors": [],
                    "warnings": []
                },
                "performance": {
                    "generation_time_ms": 123.45,
                    "memory_usage_mb": 0
                }
            }
        }
    ],
    "metadata": {
        "function_id": "func_c5a8e0c6",
        "module_id": "MOD-40",
        "created_at": "2024-01-20T10:30:00Z",
        "updated_at": "2024-01-20T10:30:00Z",
        "api_usage": {
            "type": "manual",
            "timestamp": "2024-01-20T10:30:00Z",
            "metrics": {
                "entities": 5,
                "relationships": 4,
                "attributes": 15,
                "complexity_score": 16.5
            }
        }
    }
}

4. Get ER Diagram
Endpoint: GET /{diagram_id}
Example: GET http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/er-diagrams/ERD_12345678
Description: Retrieve a specific ER diagram
Success Response:
{
    "ID": "ERD_12345678",
    "title": "ER Diagram Title",
    "description": "ER diagram description",
    "diagram": "erDiagram...",
    "raw": "raw diagram content",
    "function_id": "func_c5a8e0c6",
    "module_id": "MOD-40",
    "created_at": "2024-01-20T10:30:00Z",
    "updated_at": "2024-01-20T10:30:00Z",
    "created_by": "user123",
    "last_modified_by": "user123",
    "current_version": 1,
    "has_versions": true,
    "status": "active",
    "selected": false,
    "api_usage": {
        // API usage metrics
    }
}

5. List ER Diagram Versions
Endpoint: GET /{diagram_id}/versions
Example: GET http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/er-diagrams/ERD_12345678/versions
Description: List all versions of an ER diagram
Query Parameters:
- include_content (boolean): Include full diagram content in response
Success Response:
{
    "total": 2,
    "versions": [
        {
            "ID": "ERD_VER_12345678",
            "diagram_id": "ERD_12345678",
            "module_id": "MOD-40",
            "function_id": "func_c5a8e0c6",
            "version_number": 2,
            "function_version": 1,
            "title": "Updated ER Diagram",
            "description": "Updated version",
            "created_by": "user123",
            "created_at": "2024-01-20T11:30:00Z",
            "is_current": true,
            "diagram": "erDiagram...",  // Only if include_content=true
            "raw": "raw content"       // Only if include_content=true
        },
        {
            "ID": "ERD_VER_87654321",
            "diagram_id": "ERD_12345678",
            "module_id": "MOD-40",
            "function_id": "func_c5a8e0c6",
            "version_number": 1,
            "function_version": 1,
            "title": "Initial ER Diagram",
            "description": "Initial version",
            "created_by": "user123",
            "created_at": "2024-01-20T10:30:00Z",
            "is_current": false,
            "diagram": "erDiagram...",  // Only if include_content=true
            "raw": "raw content"       // Only if include_content=true
        }
    ]
}

6. Get Specific Version
Endpoint: GET /{diagram_id}/versions/{version_id}
Example: GET http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/er-diagrams/ERD_12345678/versions/ERD_VER_87654321
Description: Get a specific version of an ER diagram
Success Response:
{
    "version": {
        "ID": "ERD_VER_12345678",
        "diagram_id": "ERD_12345678",
        "module_id": "MOD-40",
        "function_id": "func_c5a8e0c6",
        "diagram": "erDiagram...",
        "raw": "raw content",
        "version_number": 2,
        "function_version": 1,
        "title": "Updated ER Diagram",
        "description": "Updated version",
        "created_by": "user123",
        "created_at": "2024-01-20T11:30:00Z",
        "is_current": true,
        "api_usage": {
            // API usage metrics
        }
    }
}

7. Restore Version
Endpoint: POST /{diagram_id}/restore/{version_id}
Example: POST http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/er-diagrams/ERD_12345678/restore/ERD_VER_87654321
Description: Restore an ER diagram to a specific version
Success Response:
{
    "message": "ER diagram restored to version ERD_VER_87654321 successfully",
    "diagram": {
        "ID": "ERD_12345678",
        "diagram": "erDiagram...",
        "raw": "raw content",
        "updated_at": "2024-01-20T12:30:00Z",
        "current_version": 3,
        "last_modified_by": "system_restore",
        "title": "Restored ER Diagram",
        "description": "Restored from version 1",
        "has_versions": true,
        // Other diagram fields...
    }
}

8. Update ER Diagram
Endpoint: PUT /{diagram_id}
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/er-diagrams/ERD_12345678
Description: Update an existing ER diagram
Request Body:
{
    "title": string,           // Optional
    "description": string,     // Optional
    "diagram": string,         // Optional
    "raw": string,            // Optional
    "status": string,         // Optional
    "modified_by": string,    // Required
    "change_reason": string   // Optional
}
Success Response:
{
    "message": "ER diagram updated successfully",
    "diagram": {
        "ID": "ERD_12345678",
        "title": "Updated Title",
        "description": "Updated description",
        "diagram": "erDiagram...",
        "raw": "raw content",
        "updated_at": "2024-01-20T12:30:00Z",
        "current_version": 2,
        "last_modified_by": "user123",
        "has_versions": true,
        // Other diagram fields...
    }
}

9. Activate ER Diagram
Endpoint: PUT /{diagram_id}/activate
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/er-diagrams/ERD_12345678/activate
Description: Mark an ER diagram as active
Success Response:
{
    "message": "ER diagram activated successfully",
    "diagram": {
        "ID": "ERD_12345678",
        "status": "active",
        "updated_at": "2024-01-20T12:30:00Z"
    }
}

10. Deactivate ER Diagram
Endpoint: DELETE /{diagram_id}
Example: DELETE http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/er-diagrams/ERD_12345678
Description: Mark an ER diagram as inactive
Success Response:
{
    "message": "ER diagram deactivated successfully",
    "diagram": {
        "ID": "ERD_12345678",
        "status": "inactive",
        "updated_at": "2024-01-20T12:30:00Z"
    }
}

11. Update Selection Status
Endpoint: PUT /{diagram_id}/select
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/er-diagrams/ERD_12345678/select
Description: Update ER diagram selection status
Request Body:
{
    "selected": boolean       // Whether to select this diagram
}
Success Response:
{
    "message": "ER diagram selection updated",
    "diagram": {
        "ID": "ERD_12345678",
        "selected": true,
        "updated_at": "2024-01-20T12:30:00Z"
    }
}

12. Development Tracking
Endpoint: PUT /{diagram_id}/development
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/er-diagrams/ERD_12345678/development
Description: Mark an ER diagram for development use and track its status
Request Body:
{
    "version": string,        // Development version (e.g. v1.0.0)
    "notes": string,         // Optional development notes
    "status": string         // Status: not_started/in_development/completed/archived
}
Success Response:
{
    "message": "ER diagram marked for development successfully",
    "diagram": {
        "ID": "ERD_12345678",
        "development_version": "v1.0.0",
        "development_status": "in_development",
        "development_notes": "Development in progress",
        "updated_at": "2024-01-20T12:30:00Z",
        // Other diagram fields...
    }
}

Error Responses (Common for all endpoints):

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

2. Bad Request (400):
{
    "detail": "Custom instructions are required when not using default template"
}

3. Internal Server Error (500):
{
    "detail": "Failed to save ER diagram"
}
{
    "detail": "Failed to create initial version for ER diagram"
}
{
    "detail": "Failed to update ER diagram"
}
{
    "detail": "Error in ER diagram generation: {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:

ER Diagram Document:
{
    "ID": string,                // Unique identifier
    "title": string,             // Diagram title
    "description": string,       // Diagram description
    "diagram": string,           // ER diagram content
    "raw": string,              // Raw diagram content
    "function_id": string,       // Associated function ID
    "module_id": string,         // Associated module ID
    "created_at": string,        // Creation timestamp
    "updated_at": string,        // Last update timestamp
    "created_by": string,        // Creator identifier
    "last_modified_by": string,  // Last modifier identifier
    "current_version": number,   // Current version number
    "has_versions": boolean,     // Whether versions exist
    "status": string,           // Document status
    "selected": boolean,        // Selection state
    "api_usage": {
        "type": string,         // "manual" or "generated"
        "timestamp": string,
        "metrics": {
            "entities": number,
            "relationships": number,
            "attributes": number,
            "complexity_score": number
        },
        "validation": {
            "errors": string[],
            "warnings": string[]
        },
        "performance": {
            "generation_time_ms": number,
            "memory_usage_mb": number
        }
    }
}

Version Document:
{
    "_id": string,              // Unique version identifier
    "diagram_id": string,       // Associated diagram ID
    "module_id": string,        // Associated module ID
    "function_id": string,      // Associated function ID
    "diagram": string,          // Version diagram content
    "raw": string,             // Version raw content
    "version_number": number,   // Version number
    "function_version": number, // Function version
    "title": string,           // Version title
    "description": string,     // Version description
    "created_by": string,      // Creator identifier
    "created_at": string,      // Creation timestamp
    "is_current": boolean,     // Current version flag
    "api_usage": object,       // Copy of diagram api_usage
    "generation_details": {     // Optional, for generated diagrams
        "use_default_template": boolean,
        "custom_instructions": string,
        "prompt": string
    }
}

Notes:
- All timestamps are in ISO 8601 format
- All IDs follow specific patterns:
  * Diagram IDs: "ERD_" + 8 hex characters
  * Version IDs: "ERD_VER_" + 8 hex characters
- The api_usage object structure varies between manual and generated diagrams
- Error responses always include a "detail" field with the error message
- All endpoints support CORS with OPTIONS preflight
- Diagram content must follow proper ER diagram notation
- Metrics are automatically calculated for manual diagrams
- Development tracking helps manage diagram lifecycle