classDiagram
                                          class SecurityConfig {
                                              +@EnableWebSecurity
                                              +@EnableMethodSecurity
                                              +JWT Authentication
                                              +OAuth2 Resource Server
                                              +CORS Configuration
                                              +Stateless Keycloak Endpoints
                                          }
                                          
                                          class JWTValidation {
                                              +OAuth2ResourceServer
                                              +JwtDecoder
                                              +CustomJwtGrantedAuthoritiesConverter
                                              +Bearer Token Resolver
                                          }
                                          
                                          class Authorization {
                                              +ROLE_GUEST
                                              +ROLE_MANAGE_USERS
                                              +ROLE_ADMIN
                                              +ROLE_USER
                                              +permitAll() for /people/names
                                              +authenticated() for protected endpoints
                                          }
                                          
                                          class SessionManagement {
                                              +Redis Session Storage
                                              +Session Timeout
                                              +Session Fixation
                                              +@EnableRedisHttpSession
                                              +tymb:sessions namespace
                                          }
                                          
                                          class KeycloakController {
                                              +OAuth2 Redirect
                                              +Token Exchange
                                              +User Info
                                              +Token Introspect
                                              +Dynamic redirectUri
                                          }
                                          
                                          SecurityConfig --> JWTValidation
                                          SecurityConfig --> Authorization
                                          SecurityConfig --> SessionManagement
                                          SecurityConfig --> KeycloakController
                                      

                                        classDiagram
                                          class GlobalExceptionHandler {
                                              +Chain of Responsibility
                                              +Error Response Builder
                                          }
                                          
                                          class BusinessApiExceptionHandler {
                                              +@Order(0)
                                              +BusinessException
                                          }
                                          
                                          class DataIntegrityApiExceptionHandler {
                                              +@Order(1)
                                              +DataIntegrityViolationException
                                          }
                                          
                                          class ValidationApiExceptionHandler {
                                              +@Order(2)
                                              +MethodArgumentNotValidException
                                          }
                                          
                                          class DefaultApiExceptionHandler {
                                              +@Order(Integer.MAX_VALUE)
                                              +Generic Exception
                                          }
                                          
                                          GlobalExceptionHandler --> BusinessApiExceptionHandler
                                          GlobalExceptionHandler --> DataIntegrityApiExceptionHandler
                                          GlobalExceptionHandler --> ValidationApiExceptionHandler
                                          GlobalExceptionHandler --> DefaultApiExceptionHandler
                                      

                                      graph LR
    A[Backend<br/>Spring Boot<br/>REST Endpoints] --> B[RabbitMQ<br/>Message Queue]
    B --> C[Consumer<br/>Spring Boot<br/>JDBC Processing]
    C --> D[PostgreSQL<br/>Database]
    
    %% Vivid, high-contrast class colors for light theme
    classDef producer fill:#bbdefb,stroke:#1e88e5,color:#0b1a33
    classDef mq fill:#e1bee7,stroke:#8e24aa,color:#0b1a33
    classDef consumer fill:#c8e6c9,stroke:#2e7d32,color:#0b1a33
    classDef database fill:#ffcdd2,stroke:#c62828,color:#0b1a33
    
    class A producer
    class B mq
    class C consumer
    class D database
                                    

                                      flowchart LR
                                      user["User"] -->|SSH 22| bastion["Bastion (Public Subnet)"]

                                      subgraph OCI VCN
                                        direction LR

                                        subgraph Public["Public Subnets"]
                                          bastion
                                          pubLB["Public LB Subnet (OCI LB - Reserved IP)"]
                                        end

                                        subgraph Private["Private Subnets"]
                                          operator["Operator VM"]
                                          cp["OKE Control Plane (Private Endpoint)"]
                                          workers["Worker Nodes (NodePool size=2, A1.Flex 1c/8GB/50GB)"]
                                          intLB["Internal LB Subnet"]
                                        end

                                        subgraph Gateways["Network Gateways"]
                                          ig["Internet Gateway"]:::net
                                          nat["NAT Gateway"]:::net
                                          sg["Service Gateway"]:::net
                                        end

                                        pubRT["Public Route Table"]:::net --> ig
                                        privRT["Private Route Table"]:::net --> nat
                                        privRT --> sg

                                        bastion -.-> pubRT
                                        pubLB -.-> pubRT

                                        operator -.-> privRT
                                        workers -.-> privRT
                                        intLB -.-> privRT
                                      end

                                      bastion -->|SSH Proxy| operator
                                      operator -->|kubectl 6443| cp
                                      pubLB --> workers
                                      intLB --> workers

                                      %% Improve contrast with vivid class definitions
                                      classDef host fill:#eef3fb,stroke:#1f5bff,color:#0b1a33;
                                      classDef control fill:#ede7f6,stroke:#5e35b1,color:#0b1a33;
                                      classDef compute fill:#e8f5e9,stroke:#43a047,color:#0b1a33;
                                      classDef net fill:#fff3e0,stroke:#fb8c00,color:#0b1a33;

                                      %% Assign classes for better differentiation
                                      class bastion host;
                                      class pubLB,intLB,cp control;
                                      class operator,workers compute;
                                      class pubRT,privRT net;
                                    

                                        graph TD
  %% User and Entry
  U["User"] --> Q["ask-with-model API<br/>question"]
  Q --> P["Full-text Retrieval Pipeline"]

  %% Retrieval Process
  subgraph "Pipeline"
    P --> N["Normalize/Lowercase<br/>trim punctuation"]
    N --> E{"Compute Embedding?"}
    E -- Yes --> EM["OpenAI Embeddings<br/>(text-embedding-3-small) → qvec"]
    E -- No --> SKIP["Skip vector branch"]

    %% PostgreSQL Retrieval (Trigram & Vector)
    subgraph "PostgreSQL"
      direction LR
      PG1["Trigram Search<br/>content % :query<br/>similarity(content, :query) as text_sim"]:::trgm
      PG2["Vector Search<br/>1 - (embedding <=> :qvec) as vec_sim"]:::vec
      IDX1["GIN Index<br/>idx_articles_content_trgm<br/>(content gin_trgm_ops)"]:::idx
      IDX2["IVFFlat Index<br/>idx_articles_embedding_ivfcos<br/>(embedding vector_cosine_ops)"]:::idx
      EXT1["EXTENSION pg_trgm<br/>set_limit(:min_sim)"]:::ext
      EXT2["EXTENSION pgvector"]:::ext
    end

    EM --> PG2
    SKIP -.-> PG1
    N --> PG1
    PG1 --> MRG["Merge & Rank<br/>score = 0.6*text_sim + 0.4*vec_sim"]
    PG2 --> MRG
    MRG --> TOPK["Top-K Articles"]
  end

  %% Post-processing and Response
  TOPK --> CTX["Build Context from Articles<br/>(title + snippet)"]
  CTX --> AI["LLM Call (OpenAI/Gemini/Qwen/Mock)"]
  AI --> RESP["Answer + Citations/No Knowledge Notice"]
  RESP --> RDS["Redis ChatHistory<br/>chat:session:{sid}"]
  RESP --> OUT["API Response"]

  %% Database Table and Indexes
  subgraph "articles schema"
    TBL["articles<br/>- id BIGSERIAL PK<br/>- file_path VARCHAR(500) UNIQUE<br/>- content TEXT NOT NULL<br/>- file_date TIMESTAMP NOT NULL<br/>- embedding vector"]:::tbl
  end
  TBL -. indexed by .-> IDX1
  TBL -. indexed by .-> IDX2

  %% Styles
  classDef trgm fill:#e3f2fd,stroke:#1e88e5,stroke-width:1px
  classDef vec fill:#fce4ec,stroke:#d81b60,stroke-width:1px
  classDef idx fill:#fff3e0,stroke:#fb8c00,stroke-width:1px
  classDef ext fill:#ede7f6,stroke:#5e35b1,stroke-width:1px
  classDef tbl fill:#f1f8e9,stroke:#43a047,stroke-width:1px
                                      

                                        graph TB
    subgraph "Frontend Layer"
        A[User Interface] --> B[API Client]
    end

    subgraph "API Layer"
        B --> A1[ask-with-model<br/>Async Processing]
        B --> A2[task-status<br/>Task Status Query]
        B --> A3[available-models<br/>Available Models List]
        B --> A4[add-model<br/>Add Model]
        B --> A5[chat-history<br/>Chat History]
        B --> A6[legacy-chat-history<br/>Legacy Chat History]
        B --> A7[healthz<br/>Health Check]
    end

    subgraph "Processing Layer"
        P1[Async Processing<br/>Celery Task]
        P2[Task Status Management<br/>Redis/Celery]
    end

    subgraph "Agent Service Layer"
        AS[MayaAgentService<br/>Unified Service Entry]
    end

    subgraph "Workflow Layer"
        WF[MayaAgentWorkflow<br/>Graphical Workflow]
        N1[Intent Classification Node<br/>FilterChain]
        N2[Knowledge Retrieval Node<br/>KMSourceManager]
        N3[Tool Selection Node<br/>Smart Tool Selection]
        N4[Tool Execution Node<br/>PDF/OCR/Calculation/Search]
        N5[AI Response Generation Node<br/>LLM Call]
        N6[Result Saving Node<br/>Data Persistence]
        N7[Error Handling Node<br/>Exception Handling]
    end

    subgraph "Capability Support Layer"
        LLM[LLM Capability<br/>OpenAI/Gemini/Qwen]
        TOOLS[Tool Capability<br/>PDF/OCR/Calculation/Search]
        MEMORY[Memory Capability<br/>Redis/Vector Memory]
        RAG[RAG Capability<br/>pgvector/Hybrid Retrieval]
    end

    subgraph "Data Layer"
        D1[(PostgreSQL<br/>Conversations/Articles)]
        D2[(Redis<br/>Cache/Memory/Celery)]
        D3[(RabbitMQ<br/>Celery Broker)]
    end

    subgraph "External Systems"
        E1[Paprika API<br/>Knowledge Base Content]
        E2[OpenAI API<br/>GPT-4o/GPT-4.1]
        E3[Google Gemini API<br/>Gemini Pro/Flash]
        E4[Qwen API<br/>Qwen Turbo/Plus]
    end

    %% API to Processing Layer
    A1 --> P1
    A2 --> P2

    %% Processing Layer to Agent Service Layer
    P1 --> AS

    %% Agent Service Layer to Workflow Layer
    AS --> WF

    %% Workflow Node Connections
    WF --> N1
    WF --> N2
    WF --> N3
    WF --> N4
    WF --> N5
    WF --> N6
    WF --> N7

    %% Workflow Nodes to Capability Layer
    N1 --> LLM
    N2 --> RAG
    N3 --> TOOLS
    N4 --> TOOLS
    N5 --> LLM
    N6 --> MEMORY

    %% Capability Layer to Data Layer
    LLM --> D1
    TOOLS --> D1
    MEMORY --> D2
    RAG --> D1

    %% Celery Tasks to Data Layer
    P1 --> D3
    P2 --> D2

    %% External System Connections
    LLM --> E2
    LLM --> E3
    LLM --> E4
    RAG --> E1

    %% Style Definitions
    classDef api fill:#e8f5e8,stroke:#4caf50,stroke-width:3px,color:#000000
    classDef process fill:#fff8e1,stroke:#ffa000,stroke-width:3px,color:#000000
    classDef agent fill:#e3f2fd,stroke:#2196f3,stroke-width:3px,color:#000000
    classDef workflow fill:#fff3e0,stroke:#ff9800,stroke-width:3px,color:#000000
    classDef capability fill:#fce4ec,stroke:#e91e63,stroke-width:3px,color:#000000
    classDef data fill:#f1f8e9,stroke:#43a047,stroke-width:3px,color:#000000
    classDef external fill:#f3e5f5,stroke:#9c27b0,stroke-width:3px,color:#000000

    class A1,A2,A3,A4,A5,A6,A7 api
    class P1,P2 process
    class AS agent
    class WF,N1,N2,N3,N4,N5,N6,N7 workflow
    class LLM,TOOLS,MEMORY,RAG capability
    class D1,D2,D3 data
    class E1,E2,E3,E4 external
                                      

                                        sequenceDiagram
    participant U as User
    participant F as Frontend
    participant A as API
    participant C as Celery Worker
    participant DB as Database

    U->>F: Send Question
    F->>A: POST /maya-v2/ask-with-model/
    A->>DB: Create Task Record
    A->>C: Send Processing Task
    A-->>F: Return task_id
    F-->>U: Show Processing

    loop Poll Status
        F->>A: GET /maya-v2/task-status/{task_id}
        A->>C: Query Task Status
        C-->>A: Return Status

        alt Task Complete
            A-->>F: Return AI Response
            F-->>U: Display Result
        else Processing
            F-->>U: Show Processing
        end
    end
                                      

                                              flowchart TD
    subgraph "API Layer"
        APIRouter["FastAPI Router<br/>(maya_sawa/api/qa.py)"]
    end

    subgraph "Q&A Layer"
        QAChain["QAChain"]
        PageAnalyzer["PageAnalyzer"]
    end

    subgraph "Support Layer"
        NameDetector["NameDetector"]
        ProfileManager["ProfileManager"]
        PeopleWeaponManager["PeopleWeaponManager"]
        PersonalityPromptBuilder["PersonalityPromptBuilder"]
        NameAdapter["NameAdapter"]
        VectorStore["PostgresVectorStore"]
        ChatHistoryManager["ChatHistoryManager"]
        ConfigManager["ConfigManager"]
        ConnectionPoolManager["ConnectionPoolManager"]
        Scheduler["ArticleSyncScheduler"]
    end

    subgraph "External Services"
        OpenAIAPI["OpenAI API<br/>Chat & Embeddings"]
        PeopleAPI["People System API<br/>/tymb/people/*"]
        ArticleAPI["Public Article API<br/>/paprika/articles"]
        PostgresDB["PostgreSQL"]
        RedisDB["Redis"]
    end

    Client["Client / Frontend"] --> APIRouter
    APIRouter --> QAChain
    APIRouter --> PageAnalyzer
    APIRouter --> VectorStore
    APIRouter --> ChatHistoryManager
    APIRouter --> Scheduler

    ChatHistoryManager --> RedisDB

    QAChain --> NameDetector
    QAChain --> ProfileManager
    QAChain --> PeopleWeaponManager
    QAChain --> PersonalityPromptBuilder
    QAChain --> NameAdapter
    QAChain --> VectorStore

    PageAnalyzer --> QAChain

    NameDetector --> OpenAIAPI
    QAChain --> OpenAIAPI

    ProfileManager --> PeopleAPI
    PeopleWeaponManager --> PeopleAPI

    VectorStore --> PostgresDB
    VectorStore --> ArticleAPI

    PeopleWeaponManager --> PostgresDB

    ConfigManager --> PostgresDB
    ConnectionPoolManager --> PostgresDB
    Scheduler --> ArticleAPI