# Screen API Documentation

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

1. Generate Screen
Endpoint: POST /api/modules/{module_id}/functions/{function_id}/screens/generate
Example: POST http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/screens/generate
Description: Generates screen diagrams using Claude AI
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)
Request Body:
{
    "use_default_template": boolean (required) - Whether to use default prompt template,
    "custom_instructions": string (optional) - Custom generation instructions
}
Response:
{
    "status": "success",
    "message": "Screens generated successfully",
    "data": {
        "screens": [
            {
                "ID": string,
                "ascii_content": string,
                "raw": string,
                "elements": array,
                "navigations": array,
                "status": string,
                "selected": boolean,
                "current_version": integer,
                "has_versions": boolean,
                "created_at": datetime,
                "updated_at": datetime,
                "created_by": string,
                "last_modified_by": string,
                "api_usage": object,
                "title": string,
                "description": string
            }
        ],
        "metadata": {
            "total_count": integer,
            "created_at": datetime,
            "updated_at": datetime,
            "function_id": string,
            "module_id": string,
            "api_usage": object,
            "function_current_version": integer
        }
    }
}

2. Create Screen Manually
Endpoint: POST /api/modules/{module_id}/functions/{function_id}/screens/manual
Example: POST http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/screens/manual
Description: Create a new screen with manual ASCII content
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)
Request Body:
{
    "title": string (required) - Screen title,
    "description": string (required) - Screen description,
    "ascii_content": string (required) - ASCII representation of the screen,
    "created_by": string (required) - Creator identifier
}
Response:
{
    "status": "success",
    "message": "Screen created successfully",
    "data": {
        "screen": {
            "ID": string,
            "ascii_content": string,
            "raw": string,
            "elements": array,
            "navigations": array,
            "status": string,
            "selected": boolean,
            "current_version": integer,
            "has_versions": boolean,
            "created_at": datetime,
            "updated_at": datetime,
            "created_by": string,
            "last_modified_by": string,
            "api_usage": object,
            "title": string,
            "description": string
        }
    }
}

3. Get Specific Screen
Endpoint: GET /api/modules/{module_id}/functions/{function_id}/screens/specific/{screen_id}
Example: GET http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/screens/specific/SCR_12345678
Description: Get a specific screen by its ID
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)
- screen_id (required): The ID of the screen (e.g., SCR_12345678)
Response:
{
    "status": "success",
    "message": "Screen retrieved successfully",
    "data": {
        "screen": {
            "ID": string,
            "ascii_content": string,
            "raw": string,
            "elements": array,
            "navigations": array,
            "status": string,
            "selected": boolean,
            "current_version": integer,
            "has_versions": boolean,
            "created_at": datetime,
            "updated_at": datetime,
            "created_by": string,
            "last_modified_by": string,
            "api_usage": object,
            "title": string,
            "description": string
        }
    }
}

4. List Screens
Endpoint: GET /api/modules/{module_id}/functions/{function_id}/screens/
Example: GET http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/screens/
Description: List all screens for a 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)
Query Parameters:
- search (optional): Search term for filtering screens
- include_inactive (optional): Include inactive screens in results (default: false)
Response:
{
    "status": "success",
    "message": "Screens retrieved successfully",
    "data": {
        "total": integer,
        "screens": [
            {
                "ID": string,
                "ascii_content": string,
                "raw": string,
                "elements": array,
                "navigations": array,
                "status": string,
                "selected": boolean,
                "current_version": integer,
                "has_versions": boolean,
                "created_at": datetime,
                "updated_at": datetime,
                "created_by": string,
                "last_modified_by": string,
                "api_usage": object,
                "title": string,
                "description": string
            }
        ],
        "metadata": {
            "total_count": integer,
            "created_at": datetime,
            "updated_at": datetime,
            "function_id": string,
            "module_id": string,
            "api_usage": object,
            "function_current_version": integer
        }
    }
}

5. Update Screen
Endpoint: PUT /api/modules/{module_id}/functions/{function_id}/screens/{screen_id}
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/screens/SCR_12345678
Description: Update a screen's content and metadata
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)
- screen_id (required): The ID of the screen (e.g., SCR_12345678)
Request Body:
{
    "ascii_content": string (optional) - New ASCII content,
    "elements": array (optional) - Updated elements,
    "navigations": array (optional) - Updated navigations,
    "status": string (optional) - New status,
    "title": string (optional) - New title,
    "description": string (optional) - New description,
    "modified_by": string (required) - User making the modification,
    "change_reason": string (optional) - Reason for change
}
Response:
{
    "status": "success",
    "message": "Screen updated successfully",
    "data": {
        "screen": {
            "ID": string,
            "ascii_content": string,
            "raw": string,
            "elements": array,
            "navigations": array,
            "status": string,
            "selected": boolean,
            "current_version": integer,
            "has_versions": boolean,
            "created_at": datetime,
            "updated_at": datetime,
            "created_by": string,
            "last_modified_by": string,
            "api_usage": object,
            "title": string,
            "description": string
        }
    }
}

6. Mark Screen for Development
Endpoint: PUT /api/modules/{module_id}/functions/{function_id}/screens/{screen_id}/development
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/screens/SCR_12345678/development
Description: Update screen's development status and information
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)
- screen_id (required): The ID of the screen (e.g., SCR_12345678)
Request Body:
{
    "version": string (required) - Development version (e.g. v1.0.0),
    "notes": string (optional) - Additional development notes,
    "status": string (required) - Status (not_started/in_development/completed/archived)
}
Response:
{
    "status": "success",
    "message": "Screen development status updated successfully",
    "data": {
        "screen": {
            "ID": string,
            "development": {
                "version": string,
                "notes": string,
                "status": string
            },
            "updated_at": datetime
        }
    }
}

7. Activate Screen
Endpoint: PUT /api/modules/{module_id}/functions/{function_id}/screens/{screen_id}/activate
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/screens/SCR_12345678/activate
Description: Activate a screen
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)
- screen_id (required): The ID of the screen (e.g., SCR_12345678)
Response:
{
    "status": "success",
    "message": "Screen activated successfully",
    "data": {
        "screen": {
            "ID": string,
            "status": "active",
            "updated_at": datetime
        }
    }
}

8. Deactivate Screen
Endpoint: DELETE /api/modules/{module_id}/functions/{function_id}/screens/{screen_id}
Example: DELETE http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/screens/SCR_12345678
Description: Deactivate a screen
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)
- screen_id (required): The ID of the screen (e.g., SCR_12345678)
Response:
{
    "status": "success",
    "message": "Screen deactivated successfully",
    "data": {
        "screen": {
            "ID": string,
            "status": "inactive",
            "updated_at": datetime
        }
    }
}

9. Update Screen Selection
Endpoint: PUT /api/modules/{module_id}/functions/{function_id}/screens/{screen_id}/select
Example: PUT http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/screens/SCR_12345678/select
Description: Update screen selection status (deselects all other screens when selecting)
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)
- screen_id (required): The ID of the screen (e.g., SCR_12345678)
Request Body:
{
    "selection": boolean (required) - Selection status
}
Response:
{
    "status": "success",
    "message": "Screen selection updated",
    "data": {
        "screen": {
            "ID": string,
            "selected": boolean,
            "updated_at": datetime
        }
    }
}

10. List Screen Versions
Endpoint: GET /api/modules/{module_id}/functions/{function_id}/screens/{screen_id}/versions
Example: GET http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/screens/SCR_12345678/versions
Description: List all versions of a screen
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)
- screen_id (required): The ID of the screen (e.g., SCR_12345678)
Query Parameters:
- include_content (optional): Include full screen content in response (default: false)
Response:
{
    "status": "success",
    "message": "Screen versions retrieved successfully",
    "data": {
        "total": integer,
        "versions": [
            {
                "ID": string,
                "screen_id": string,
                "module_id": string,
                "function_id": string,
                "version_number": integer,
                "function_version": integer,
                "created_at": datetime,
                "created_by": string,
                "api_usage": object,
                "is_current": boolean,
                "title": string,
                "description": string,
                "ascii_content": string (if include_content=true),
                "raw": string (if include_content=true),
                "elements": array (if include_content=true),
                "navigations": array (if include_content=true)
            }
        ]
    }
}

11. Get Screen Version
Endpoint: GET /api/modules/{module_id}/functions/{function_id}/screens/{screen_id}/versions/{version_id}
Example: GET http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/screens/SCR_12345678/versions/VER_87654321
Description: Get a specific version of a screen
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)
- screen_id (required): The ID of the screen (e.g., SCR_12345678)
- version_id (required): The ID of the version (e.g., VER_87654321)
Response:
{
    "status": "success",
    "message": "Screen version retrieved successfully",
    "data": {
        "version": {
            "ID": string,
            "screen_id": string,
            "module_id": string,
            "function_id": string,
            "version_number": integer,
            "function_version": integer,
            "created_at": datetime,
            "created_by": string,
            "api_usage": object,
            "is_current": boolean,
            "title": string,
            "description": string,
            "ascii_content": string,
            "raw": string,
            "elements": array,
            "navigations": array
        }
    }
}

12. Restore Screen Version
Endpoint: POST /api/modules/{module_id}/functions/{function_id}/screens/{screen_id}/restore/{version_id}
Example: POST http://localhost:8000/api/modules/MOD-40/functions/func_c5a8e0c6/screens/SCR_12345678/restore/VER_87654321
Description: Restore a screen to a specific version
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)
- screen_id (required): The ID of the screen (e.g., SCR_12345678)
- version_id (required): The ID of the version to restore (e.g., VER_87654321)
Response:
{
    "status": "success",
    "message": "Screen restored successfully",
    "data": {
        "screen": {
            "ID": string,
            "ascii_content": string,
            "raw": string,
            "elements": array,
            "navigations": array,
            "status": string,
            "selected": boolean,
            "current_version": integer,
            "has_versions": boolean,
            "created_at": datetime,
            "updated_at": datetime,
            "created_by": string,
            "last_modified_by": "system_restore",
            "api_usage": object,
            "title": string,
            "description": string
        }
    }
}

Models:

Screen Element:
{
    "name": string (required) - Element name,
    "type": string (required) - Element type (button, input, text, etc),
    "position": {
        "x": integer (required) - X coordinate,
        "y": integer (required) - Y coordinate
    },
    "properties": object (optional) - Additional properties,
    "parent_container": string (optional) - Parent container if nested
}

Screen Navigation:
{
    "from_screen": string (required) - Source screen name,
    "to_screen": string (required) - Target screen name,
    "trigger_element": string (required) - Element triggering navigation,
    "conditions": object (optional) - Navigation conditions
}

Status Codes:
- 200: Successful operation
- 201: Resource created successfully
- 400: Bad request (invalid input)
- 404: Resource not found
- 500: Internal server error

Error Response Format:
{
    "status": "error",
    "message": string,
    "error_code": string
}

Screen Status Values:
- "active": Currently active
- "inactive": Not active
- "draft": In draft state
- "archived": Archived screen
- "in_review": Under review
- "approved": Approved for use
- "rejected": Rejected after review

Development Status Values:
- "not_started": Development not started
- "in_development": Currently being developed
- "completed": Development completed
- "archived": Development archived

Authentication:
- All endpoints require authentication via Bearer token
- Include token in Authorization header: "Authorization: Bearer <token>"

Notes:
- All datetime values are in ISO 8601 format
- All string fields have a maximum length of 1000 characters unless specified otherwise
- The system automatically handles versioning when updates are made
- Screens are associated with specific modules and functions
- The API supports CORS with OPTIONS preflight requests
- ASCII content should follow standard ASCII art conventions
- Screen elements and navigations are optional but recommended for better documentation