Skip to content

Feature: AI-Enhanced Workflow (AIEW)

1. Business Rationale

To enhance user productivity and streamline system interaction, we will introduce an AI-powered chat component. This will allow users to perform system operations and query the knowledge base using natural language, reducing the need for manual navigation and extensive training. The inclusion of a confirmation step for all data-modifying actions ensures safety and user control. This is formally documented in the ADR for AI-Enhanced Workflow Integration.

2. Scope

2.1. In-Scope

  • A chat interface integrated into the existing React frontend.
  • Natural language processing for a pre-defined set of user queries and system commands.
  • Slash commands (e.g., /group, /knowledge) for structured, intent-specific operations.
  • Knowledge base queries that search and synthesize content from the project's /docs directory.
  • A mandatory user confirmation step before executing any data-modifying operation.
  • Strict adherence to the existing security model (authentication and authorization).
  • Auditing of all operations initiated via the chat interface.
  • Introduction of two new backend services: ai_service for orchestration and mcp_service for tool integration.
  • Retrieval and continuation of past chat sessions.

2.2. Out-of-Scope

  • General-purpose, open-ended AI conversation. The assistant will only respond to supported commands and queries.
  • User interface customization for the chat component beyond initial integration.
  • Any functionality not explicitly defined in the approved toolset for the MCP server.

3. Functional Requirements

  • FR-1: Chat Interface: The system shall display a chat widget (e.g., Rasa Wechat) within the main application shell for authenticated users.
  • FR-2: Command & Intent Recognition: The system must interpret user's natural language input to identify their intent and map it to a defined function.
  • FR-3: Slash Commands: The system must support slash commands for direct access to specific functionalities (e.g., /group add_user, /knowledge search).
  • FR-4: Role-Based Access Control (RBAC): All actions performed via chat must be validated against the user's current permissions. The user should receive an "unauthorized" message if they attempt an action beyond their access level.
  • FR-5: Audit Trail: All commands, whether successful, canceled, or failed, must be logged in the security audit trail.
  • FR-6: Operational Plan Confirmation: For any operation that will create, update, or delete data, the system must first present a clear execution plan to the user and require explicit confirmation before proceeding.
  • FR-7: Chat History: The system must allow users to find and resume past conversations. This will be accessible via a UI button. When a user types the "@" command, the UI must trigger an auto-complete list of previous sessions, sorted in descending chronological order. The user can then select a session to resume.
  • FR-8: Slash Command Definitions: The system shall support a pre-defined set of slash commands for direct actions. The initial set includes:
Command Example Description
/group /group addUser --user "jdoe" --group "auditors" Manages user groups.
/user /user find --email "jdoe@example.com" Manages user accounts.
/knowledge /knowledge search "password reset" Searches the documentation.
/audit /audit view --user "jdoe" Queries the audit trail.
  • FR-9: Error Propagation: If an operation fails for technical reasons after being confirmed (e.g., a downstream service is unavailable), the system must return a clear, user-friendly error message explaining the failure.

4. Non-Functional Requirements

  • NFR-1: Security: The ai_service and mcp_service must not be publicly exposed. All interactions must be routed through the authenticated api_gateway.
  • NFR-2: Performance: Simple queries should have a response time of under 3 seconds. Complex operations should provide immediate acknowledgment and a plan for confirmation.
  • NFR-3: Data Persistence: The ai_service will use Redis for short-term session/conversation state and MongoDB for long-term retention and analysis. A data retention policy for chat history should be established.

5. High-Level Workflow (Verified with Confirmation Step)

  1. User Input: User sends a query/command through the chat UI.
  2. Gateway Routing: The query is sent to a new endpoint on the api_gateway (e.g., /api/ai).
  3. Intent Processing: The api_gateway forwards the request to the internal ai_service.
  4. Orchestration & Plan Presentation: The ai_service uses the LLM (Gemini) to determine user intent and then leverages LangGraph to construct an execution plan. For data-modifying operations, this plan is presented to the user for approval. For read-only queries, this step is skipped.
  5. User Confirmation: The user reviews the plan (e.g., "I will now add user 'jdoe' to the 'auditors' group.") and clicks "Confirm" or "Cancel". If canceled, the workflow stops. If confirmed, it proceeds.
  6. Tool Execution: LangGraph calls the necessary tools via the mcp_service. The mcp_service acts as a secure adapter, translating these calls into requests to our existing internal APIs.
  7. Response Synthesis: LangGraph receives the results from the tools and uses the LLM to generate a final, user-friendly summary.
  8. Return Journey: The response is sent back through the api_gateway to the user's chat UI.
sequenceDiagram
    participant User
    participant Frontend
    participant API Gateway
    participant AI Service
    participant MCP Service
    participant Internal APIs

    User->>Frontend: 1. Sends query/command
    Frontend->>API Gateway: 2. Forwards query to /api/ai
    API Gateway->>AI Service: 3. Forwards authenticated request

    AI Service->>AI Service: 4. Constructs execution plan (via LangGraph)

    alt Data-Modifying Operation
        AI Service-->>API Gateway: 5a. Sends plan for approval
        API Gateway-->>Frontend: 5b. Forwards plan
        Frontend-->>User: 5c. Displays plan and asks for confirmation

        User->>Frontend: 6a. Clicks "Confirm"
        Frontend->>API Gateway: 6b. Sends confirmation
        API Gateway->>AI Service: 6c. Forwards confirmation

        AI Service->>MCP Service: 7. Executes tool via secure adapter
        MCP Service->>Internal APIs: 8. Calls relevant internal API
        Internal APIs-->>MCP Service: 9. Returns result
        MCP Service-->>AI Service: 10. Returns result to orchestrator

    else Read-Only Query
        AI Service->>MCP Service: 7 (alt). Executes read-only tool
        MCP Service->>Internal APIs: 8 (alt). Calls internal API
        Internal APIs-->>MCP Service: 9 (alt). Returns data
        MCP Service-->>AI Service: 10 (alt). Returns data
    end

    AI Service->>AI Service: 11. Synthesizes final response (via LLM)
    AI Service-->>API Gateway: 12a. Sends final response
    API Gateway-->>Frontend: 12b. Forwards response
    Frontend-->>User: 12c. Displays final response in chat