WordPress AI Question Plugin Flowchart

1. Logic Flowchart

flowchart TD
    %% Nodes
    Start([User Visits Post])
    AuthCheck{Is User Logged In?}
    ShowPartial[Show Partial Content / Login Prompt]
    ShowFull[Show Full Content & Init Script]
    
    %% Selection Flow
    UserSelects[User Selects Text Fragment]
    ShowButton[Show 'Ask AI' Button near selection]
    ClickButton{User Clicks Button?}
    
    %% Chat Creation
    GenID[Generate Unique ID]
    Highlight["Highlight Text Fragment \n(Apply CSS Class with ID)"]
    OpenSidebar["Open New Chat Block in Sidebar \n(Linked by ID)"]
    
    %% Question Flow
    UserAsks[User Types Question & Clicks Send]
    CheckCredits{"Check User Credits \n(API Call)"}
    
    %% Credit Logic
    Insufficient[Insufficient Funds]
    ShowTopUp[Show Top-Up / Backup Modal]
    TopUpAction[User Tops Up]
    
    %% Remote Processing
    Sufficient[Credits Available]
    SendRemote["Send Data to Remote Server: \nUser ID, Post ID, Selection, Question"]
    
    subgraph Remote Server
        SaveSel["Save Selection to DB \n(Table 1)"]
        ProcessAI[Process Question with AI Agent]
        SaveQA["Save Q&A to DB \n(Table 2 - Linked to Table 1)"]
        Deduct[Deduct Credits from User Account]
    end
    
    %% Response
    ReturnAns[Return Formatted Answer]
    DisplayAns[Display Answer in Sidebar Chat]
    
    %% Close/Archive Flow
    CloseChat{User Clicks Close?}
    CheckActivity{Has Questions?}
    ArchiveChat["Archive Chat \n(Hide Block, Keep Data)"]
    DeleteChat["Delete Chat \n(Remove Block & Highlight)"]
    RemoveHighlight["Remove Text Highlight \n(Unwrap Text)"]

    %% Connections
    Start --> AuthCheck
    AuthCheck -- No --> ShowPartial
    AuthCheck -- Yes --> ShowFull
    ShowFull --> UserSelects
    UserSelects --> ShowButton
    ShowButton --> ClickButton
    ClickButton -- No --> UserSelects
    ClickButton -- Yes --> GenID
    GenID --> Highlight
    Highlight --> OpenSidebar
    OpenSidebar --> UserAsks
    UserAsks --> CheckCredits
    
    CheckCredits -- No --> Insufficient
    Insufficient --> ShowTopUp
    ShowTopUp --> TopUpAction
    TopUpAction --> CheckCredits
    
    CheckCredits -- Yes --> Sufficient
    Sufficient --> SendRemote
    SendRemote --> SaveSel
    SaveSel --> ProcessAI
    ProcessAI --> SaveQA
    SaveQA --> Deduct
    Deduct --> ReturnAns
    ReturnAns --> DisplayAns
    
    DisplayAns --> CloseChat
    OpenSidebar --> CloseChat
    CloseChat -- Yes --> CheckActivity
    CheckActivity -- No --> DeleteChat
    CheckActivity -- Yes --> ArchiveChat
    DeleteChat --> RemoveHighlight

2. Database Schema (Remote Server)

erDiagram
    USERS ||--o{ SELECTIONS : creates
    SELECTIONS ||--o{ QA_LOGS : contains

    USERS {
        int user_id PK "WordPress User ID"
        int credit_balance "Current Credits"
    }

    SELECTIONS {
        int record_id PK "Unique Selection ID"
        int user_id FK "Link to User"
        int post_id "WordPress Post ID"
        text selected_text "The actual text fragment"
        string dom_id "Frontend DOM ID for highlighting"
        datetime created_at
    }

    QA_LOGS {
        int qa_id PK
        int record_id FK "Link to SELECTIONS table"
        text question "User's Question"
        text ai_answer "Formatted AI Response"
        int tokens_used "Cost calculation"
        int order "Order in conversation"
        datetime date "Date of interaction"
        datetime created_at
    }

3. Interaction Sequence Diagram

sequenceDiagram
    actor User
    participant Browser as WP Frontend (JS)
    participant Plugin as WP Backend (PHP)
    participant Remote as Remote AI Service
    participant DB as Remote DB

    User->>Browser: Selects Text Fragment
    Browser->>User: Shows "Ask AI" Button
    User->>Browser: Clicks "Ask AI"
    Browser->>Browser: Highlights Text (CSS)
    Browser->>Browser: Opens Sidebar Chat Block
    
    User->>Browser: Types Question & Clicks Send
    Browser->>Plugin: Check Credits (User ID)
    Plugin->>Remote: API: Get Balance
    Remote->>DB: Query Balance
    DB-->>Remote: Return Balance
    Remote-->>Plugin: Balance OK
    Plugin-->>Browser: Proceed
    
    alt Insufficient Credits
        Browser->>User: Show Top-Up Modal
    else Sufficient Credits
        Browser->>Remote: Send Question Payload
        Note right of Browser: Payload: {UserID, PostID, Selection, Question}
        
        Remote->>DB: Save Selection (Table 1)
        Remote->>Remote: Process with AI Agent
        Remote->>DB: Save Q&A (Table 2)
        Remote->>DB: Deduct Credits
        
        Remote-->>Browser: Return Formatted Answer
        Browser->>User: Display Answer in Sidebar
    end
    
    opt Close Chat
        User->>Browser: Clicks Close
        Browser->>Browser: Remove Chat Block
        Browser->>Browser: Remove Text Highlight
    end