# Module Contracts: LLM Chat Assistant for Project Operations

## Backend Assistant Orchestrator Module

# [DEF:AssistantOrchestratorModule:Module]
# @TIER: CRITICAL
# @SEMANTICS: [assistant, intent, dispatch, safety]
# @PURPOSE: Parse chat commands, decide execution path, and orchestrate safe dispatch to existing operations.
# @LAYER: Domain
# @RELATION: DEPENDS_ON -> [DEF:AssistantIntentParserModule]
# @RELATION: DEPENDS_ON -> [DEF:AssistantSecurityGuardModule]
# @RELATION: DEPENDS_ON -> [DEF:AssistantExecutionAdapterModule]
# @RELATION: DEPENDS_ON -> [DEF:AssistantAuditLogModule]
# @INVARIANT: No operation is dispatched before permission and risk checks complete.
# @PRE: Authenticated user context and non-empty user message are provided.
# @POST: Returns one of deterministic states: needs_clarification, denied, needs_confirmation, started, success, failed.
# @POST: Long-running operation responses include task_id when task is created.
# [/DEF:AssistantOrchestratorModule]

---

## Backend Assistant Intent Parser Module

# [DEF:AssistantIntentParserModule:Module]
# @TIER: CRITICAL
# @SEMANTICS: [nlp, intent, entities, confidence]
# @PURPOSE: Convert RU/EN natural-language operation requests into normalized intent objects.
# @LAYER: Domain
# @RELATION: CALLED_BY -> [DEF:AssistantOrchestratorModule]
# @INVARIANT: Parsed intent always includes confidence score and risk_level.
# @PRE: Input text is available and sanitized.
# @POST: Returns normalized intent or unknown intent with low confidence.
# [/DEF:AssistantIntentParserModule]

---

## Backend Assistant Security Guard Module

# [DEF:AssistantSecurityGuardModule:Module]
# @TIER: CRITICAL
# @SEMANTICS: [rbac, confirmation, risk]
# @PURPOSE: Apply RBAC and dangerous-operation confirmation gates before execution.
# @LAYER: Security
# @RELATION: CALLED_BY -> [DEF:AssistantOrchestratorModule]
# @RELATION: DEPENDS_ON -> [DEF:MultiUserAuthModule]
# @INVARIANT: Dangerous operations never execute without explicit confirmation token.
# @PRE: Normalized intent and authenticated user context are available.
# @POST: Returns one of {denied, needs_confirmation, allowed}.
# [/DEF:AssistantSecurityGuardModule]

---

## Backend Assistant Execution Adapter Module

# [DEF:AssistantExecutionAdapterModule:Module]
# @TIER: CRITICAL
# @SEMANTICS: [adapter, task_manager, integrations]
# @PURPOSE: Map validated execution requests to existing Git/migration/backup/LLM/task status APIs.
# @LAYER: Integration
# @RELATION: CALLED_BY -> [DEF:AssistantOrchestratorModule]
# @RELATION: DEPENDS_ON -> [DEF:TasksRouter:Module]
# @RELATION: DEPENDS_ON -> [DEF:backend.src.api.routes.git:Module]
# @RELATION: DEPENDS_ON -> [DEF:backend.src.api.routes.migration:Module]
# @RELATION: DEPENDS_ON -> [DEF:backend/src/api/routes/llm.py:Module]
# @INVARIANT: Adapter reuses existing execution paths and does not duplicate domain logic.
# @PRE: ExecutionRequest is validated and authorized.
# @POST: Returns operation result or started task_id for async flows.
# [/DEF:AssistantExecutionAdapterModule]

---

## Backend Assistant Audit Log Module

# [DEF:AssistantAuditLogModule:Module]
# @TIER: STANDARD
# @SEMANTICS: [audit, traceability, observability]
# @PURPOSE: Persist assistant command processing decisions and outcomes.
# @LAYER: Infra
# @RELATION: CALLED_BY -> [DEF:AssistantOrchestratorModule]
# @INVARIANT: Every processed command emits one audit record.
# @PRE: Command processing context is available.
# @POST: Structured audit entry persisted with decision/outcome/task_id (if present).
# [/DEF:AssistantAuditLogModule]

---

## Backend Assistant API Module

# [DEF:AssistantApiContract:Module]
# @TIER: CRITICAL
# @SEMANTICS: [api, assistant, chat, confirm]
# @PURPOSE: Provide chat message, confirmation, and history endpoints for assistant workflows.
# @LAYER: Interface
# @RELATION: DEPENDS_ON -> [DEF:AssistantOrchestratorModule]
# @INVARIANT: API responses are deterministic and machine-readable for frontend state handling.
# @PRE: User authenticated.
# @POST: Message endpoint returns assistant response state + metadata.
# @POST: Confirm endpoint executes pending dangerous command exactly once.
# @POST: Cancel endpoint prevents execution of pending dangerous command.
# [/DEF:AssistantApiContract]

---

## Frontend Assistant Chat Panel Contract

<!-- [DEF:AssistantChatPanel:Component] -->
/**
 * @TIER: CRITICAL
 * @SEMANTICS: [ui, chat, commands, feedback]
 * @PURPOSE: Render in-app assistant conversation and operational command interactions.
 * @LAYER: UI
 * @RELATION: DEPENDS_ON -> [DEF:AssistantApiClient]
 * @RELATION: USES -> [DEF:TaskDrawerStore]
 * @INVARIANT: Every assistant response is rendered with explicit state badge.
 * @PRE: User is authenticated and assistant panel is accessible.
 * @POST: User can send command, receive response, and confirm/cancel risky operations.
 * @UX_STATE: Idle -> Prompt and examples are visible.
 * @UX_STATE: Parsing -> Temporary loading message shown.
 * @UX_STATE: NeedsConfirmation -> Confirmation card with Confirm/Cancel actions displayed.
 * @UX_STATE: Started -> task_id chip and tracking hint displayed.
 * @UX_STATE: Error -> Error card with retry/rephrase guidance displayed.
 * @UX_RECOVERY: User can rephrase ambiguous command or retry after error.
 */
<!-- [/DEF:AssistantChatPanel] -->

---

## Frontend Assistant API Client Contract

# [DEF:AssistantApiClient:Module]
# @TIER: STANDARD
# @SEMANTICS: [frontend, api_client, assistant]
# @PURPOSE: Wrap assistant API requests through existing frontend API helpers.
# @LAYER: Infra
# @RELATION: CALLS -> [DEF:AssistantApiContract]
# @INVARIANT: No direct native fetch bypassing project API wrapper conventions.
# @PRE: Valid auth context/token exists.
# @POST: Returns typed assistant response payload or structured error object.
# [/DEF:AssistantApiClient]

---

## Contract Usage Simulation (Key Scenario)

Scenario traced: User requests production deploy in chat.

1. `AssistantChatPanel` sends message to `AssistantApiClient`.
2. `AssistantApiContract` calls `AssistantOrchestratorModule`.
3. `AssistantIntentParserModule` extracts `domain=git`, `operation=deploy`, `target_env=production`, `risk_level=dangerous`.
4. `AssistantSecurityGuardModule` returns `needs_confirmation` and issues token.
5. UI shows confirmation card.
6. User confirms.
7. Confirm endpoint calls orchestrator with token.
8. `AssistantExecutionAdapterModule` dispatches existing deploy flow and returns `task_id`.
9. `AssistantAuditLogModule` records both confirmation request and final dispatch result.
10. UI shows `started` state with tracking hint (Task Drawer/reports).