OpenWiki Generation Instructions

Purpose & Target Audience

This wiki serves as a Production Developer Engineering Portal & API Specification Hub. All generated pages must provide complete technical depth, exact API contracts, background execution lifecycles, and database invariants necessary for backend and frontend engineers to build, integrate, and debug.

1. Mandatory API Contract Standards

For every API route, ViewSet, or HTTP endpoint documented in the wiki:

A. Endpoint Summary & Metadata

HTTP Method & Route: (e.g., POST /api/v1/schemas/generate/)
Controller / View Source: File path and line numbers (e.g., api/views/schema_views/schema_viewset.py)
Authentication & Authorization:
- Required Auth Types (JWT Bearer Token, API Key (X-API-Key), Microsoft SSO Session)
- Permissions required (IsAuthenticated, IsTenantAdmin, etc.)
Tenant Isolation Rules: Scope boundary (SchemaTenantMixin, tenant_id resolution)

B. Request Specification

Path & Query Parameters: Name, type, required/optional, description.
Request Headers: Expected headers (e.g., Authorization, Content-Type: application/json or multipart/form-data).
Request Body Schema:
- Serializer class reference (e.g., SchemaSerializer).
- Full JSON schema or representative JSON payload example.
- Field validation constraints (required fields, regex patterns, max lengths).

C. Response Specification & Error Contracts

Success Responses (200 OK / 201 Created / 202 Accepted):
- Exact JSON response structure and field descriptions.
Error Responses (400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity, 500 Internal Error):
- Standardized error payload shape:
```
{
  "success": false,
  "error_code": "INVALID_SCHEMA_PAYLOAD",
  "message": "Detailed error description here",
  "details": {}
}
```
- List of domain-specific error codes emitted by the endpoint.

2. Service & Async Task Execution Contracts

Do not limit service documentation to api/services/. You MUST scan and document all background execution pipelines across the repository:

A. Directory Discovery Scope

Include all service modules regardless of placement:

api/services/* (PDF processing, LiteLLM, storage, PII, parallel processing)
api/schema_generator/* (tasks.py, services/schema_generator_service/*)
api/views/document_processing_views/ & api/services/upload_processing/

B. Async Task Lifecycles (Celery & Threading)

For every background service (e.g. schema_generator.run_schema_generation_job):

Trigger: Endpoint or event that queues the task.
Executor & Queue: Celery queue name, task name, and fallback mechanism (e.g. threading.Thread local fallback).
Status State Machine: State transitions (PENDING -> PROCESSING -> COMPLETED / FAILED).
Persistence & Cleanup: Model updates (SchemaGenerationJob), file cleanup hooks (_cleanup_job_file).

3. Required Visual Diagrams

Every major domain overview page (API, Services, Schemas, Documents) MUST contain:

Mermaid Flowchart (flowchart TD): Architectural layer interactions (View -> Serializer -> Service -> Task -> Model).
Mermaid Sequence Diagram (sequenceDiagram): Step-by-step request/response and async lifecycle for key operations (e.g., Schema Generation Flow, Document Upload Flow).

4. Code & Test Verification References

Canonical Entry Points: Always provide file basenames with clickable file:// links to source files.
Automated Test Coverage: List unit and integration test paths verifying the contract (e.g., tests/unit/schema/test_schema_generator.py).