Permanently delete a project and all its associated data. Requires a valid JWT access token. The project must belong to the authenticated user’s tenant and must be in ARCHIVED status.

• This is a hard-delete operation — the project and all related data (conversations, messages, versions) are permanently removed from the database.
• Only ARCHIVED projects can be deleted. If the project is not archived, the user must archive it first (UC-03005).
• This action is irreversible — the frontend must show a confirmation dialog with a clear warning.

sequenceDiagram
    actor User

    User->>+FE: clicks "Delete Permanently" (from archived project)

    FE->>FE: show destructive confirmation dialog <br> "This action cannot be undone"
    alt user cancels
        FE-->>User: close dialog
    end

    User->>FE: confirms deletion

    FE->>+BE: DELETE /api/v1/projects/{id} <br> Authorization: Bearer {accessToken}

    BE->>BE: validate JWT access token
    alt access token invalid or missing
        BE-->>FE: 401 Unauthorized <br> ErrorResponse
    end

    BE->>DB: find project by id and tenant_id
    alt project not found
        BE-->>FE: 404 Not Found <br> ErrorResponse
    end

    BE->>BE: check project status
    alt project is not ARCHIVED
        BE-->>FE: 409 Conflict <br> ErrorResponse
    end

    BE->>DB: delete all messages for project conversations
    BE->>DB: delete all conversations for project
    BE->>DB: delete all versions for project
    BE->>DB: delete project

    BE->>-FE: 204 No Content

    FE->>-User: show success notification <br> redirect to project list

DELETE /api/v1/projects/{id} (no request body)

204 No Content (success, no body)

401 Unauthorized (missing or invalid access token) ErrorResponse:

{
  "status": 401,
  "code": "AUTHENTICATION_FAILED",
  "message": "Access token is missing or invalid"
}

404 Not Found (project does not exist or does not belong to user’s tenant) ErrorResponse:

{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "Project not found"
}

409 Conflict (project is not ARCHIVED) ErrorResponse:

{
  "status": 409,
  "code": "CONFLICT_PROJECT",
  "message": "Only archived projects can be permanently deleted"
}

Frontend

Validations

No form inputs — this is a single-action operation triggered by a button with destructive confirmation dialog.

Backend

Validations

Test Cases