Julian AI Chatbot - Complete System Flow

flowchart TD A["🔧 Plugin Activated
julian-chatbot.php"]:::system --> B["Register 3 CPTs
julian_chat_kb · julian_chat_log · julian_chat_agent"]:::system B --> C["Register Taxonomy
kb_category"]:::system C --> D["Schedule Daily Cron
Chat log cleanup (30 days)"]:::system D --> E["plugins_loaded hook
Julian_Chatbot::instance()"]:::system E --> F["Boot Post Types"]:::system E --> G["Boot Settings"]:::system E --> H["Boot AJAX Handler"]:::system E --> I["Boot Admin Panel"]:::system E --> J["Boot Public Frontend"]:::system classDef system fill:#1a2332,stroke:#3b82f6,color:#93c5fd

flowchart TD MENU["Julian Chatbot Menu
(admin_menu hook)"]:::admin MENU --> DASH["📊 Dashboard"]:::admin MENU --> KB["📚 Knowledge Base"]:::admin MENU --> AGENTS["👥 Agents"]:::admin MENU --> LOGS["💬 Chat Logs"]:::admin MENU --> SETT["⚙️ Settings"]:::admin DASH --> D1["Live Stat Cards
KB entries · Total chats · Handoffs
Today's chats · Active agents"]:::admin DASH --> D2["Recent Chats List"]:::admin DASH --> D3["Recent KB Entries"]:::admin KB --> KB1["List / Search / Paginate"]:::admin KB --> KB2["Add / Edit Q&A Entry"]:::admin KB --> KB3["Import: XML / CSV / JSON"]:::admin KB --> KB4["Export: XML / CSV / JSON"]:::admin AGENTS --> AG1["Create Agent
Name · Email · Avatar · Phone"]:::agent AGENTS --> AG2["Edit / Delete Agent"]:::agent AGENTS --> AG3["View assigned chats"]:::agent LOGS --> LG1["Table: Session ID · Visitor · Status
Agent · 👍/👎 counts · Date"]:::log LOGS --> LG2["Modal: Full Transcript
Messages + feedback badges"]:::log LOGS --> LG3["Filter by status / agent / date"]:::log SETT --> ST1["Tab: General
Enable toggle · API key · Model selector
Bot name · Handoff email"]:::admin SETT --> ST2["Tab: Appearance
Brand color · Accent color
Bot profile pic · Welcome voice toggle
Custom welcome MP3 upload"]:::admin SETT --> ST3["Tab: Knowledge
KB toggle · Auto-pull toggle
Pull limit · Content types"]:::admin SETT --> ST4["Tab: Notifications
Agent email notification toggle
Visitor confirmation email toggle"]:::admin SETT --> ST5["Tab: Chat UX
Markdown toggle · Quick replies
Widget position"]:::admin classDef admin fill:#1e1a0e,stroke:#d4a017,color:#f0c040 classDef agent fill:#2a1a0a,stroke:#f97316,color:#fdba74 classDef log fill:#2a0e0e,stroke:#ef4444,color:#fca5a5

flowchart TD V1["Visitor loads page"]:::user --> V2{"Chatbot
enabled?"}:::user V2 -- No --> V_END["No widget shown"]:::user V2 -- Yes --> V3["Floating Lottie bot toggle
renders at configured position"]:::user V3 --> V4["Visitor clicks toggle"]:::user V4 --> V5{"Voice intro
enabled &
not played?"}:::user V5 -- Yes --> V6["Play welcome MP3
(custom or default)"]:::user V6 --> V7["WebGL gradient orb animates
synced to audio via AnalyserNode"]:::user V7 --> V8{"User clicks
Skip or audio
ends?"}:::user V8 --> V9["Chat area appears
with quick reply buttons"]:::user V5 -- No --> V9 V9 --> V10["User types message
& clicks send"]:::user V10 --> V11["Send tone plays
(C5→G5 ascending)"]:::user V10 --> V12["Message added to
local history (localStorage)"]:::user V12 --> V13["AJAX POST to server
action: julian_chatbot_send"]:::user V13 --> V14["Thinking indicator
(animated 3D orb + shimmer text)"]:::user V14 --> SERVER["→ See Flow 4: Server Processing"]:::system SERVER --> V15{"Bot response
contains
[HANDOFF]?"}:::user V15 -- No --> V16["Receive tone plays
(E5→B5 chime)"]:::user V16 --> V17["Message animates in
(spring: translateY + scale)"]:::user V17 --> V18["Markdown rendered
(bold, italic, links, lists)"]:::user V18 --> V19["Thumbs up/down
+ optional comment"]:::user V19 --> V20["Feedback saved to
chat log via AJAX"]:::user V20 --> V9 V15 -- Yes --> HAND["→ See Flow 5: Handoff & Agent Assignment"]:::agent classDef user fill:#0a1f0e,stroke:#22c55e,color:#86efac classDef system fill:#1a2332,stroke:#3b82f6,color:#93c5fd classDef agent fill:#2a1a0a,stroke:#f97316,color:#fdba74

flowchart TD S1["AJAX request received
julian_chatbot_send"]:::system S1 --> S2{"Rate limit
check
(15 msg/min/IP)"}:::system S2 -- Exceeded --> S3["Return error:
'Too many messages'"]:::system S2 -- OK --> S4["Verify nonce
& sanitize input"]:::system S4 --> S5["Build system instruction
(personality + rules + markdown)"]:::system S5 --> S6{"KB enabled?"}:::system S6 -- Yes --> S7["Keyword-overlap scoring
against all KB entries"]:::system S7 --> S8["Top 10 relevant
Q&A entries selected"]:::system S8 --> S9["KB context injected into
system instruction"]:::system S6 -- No --> S10{"Auto-pull
enabled?"}:::system S10 -- Yes --> S11["WP_Query search
posts/pages/custom CPTs
via 's' parameter"]:::system S11 --> S12["Extract excerpts
inject as context"]:::system S10 -- No --> S13["No context injected"]:::system S9 --> S14["Build Gemini API call
model: gemini-2.5-flash
systemInstruction + contents"]:::ai S12 --> S14 S13 --> S14 S14 --> S15{"API call
successful?"}:::ai S15 -- No --> S16["Surface real error
to visitor + retry hint"]:::ai S15 -- Yes --> S17["Parse response text"]:::ai S17 --> S18{"Contains
[HANDOFF]?"}:::ai S18 -- No --> S19["Append bot response
to chat history (wp_slash)"]:::system S19 --> S20["Update chat log post
(julian_chat_log)"]:::log S20 --> S21["Return JSON response
to frontend"]:::system S21 --> V15["→ Back to Frontend Flow"]:::user S18 -- Yes --> HAND2["→ See Flow 5: Handoff"]:::agent classDef system fill:#1a2332,stroke:#3b82f6,color:#93c5fd classDef ai fill:#1a0a2e,stroke:#a855f7,color:#c084fc classDef log fill:#2a0e0e,stroke:#ef4444,color:#fca5a5 classDef user fill:#0a1f0e,stroke:#22c55e,color:#86efac classDef agent fill:#2a1a0a,stroke:#f97316,color:#fdba74

flowchart TD H1["Bot outputs [HANDOFF]
marker in response"]:::ai H1 --> H2{"Visitor details
already
collected?"}:::agent H2 -- No --> H3["Bot asks for name"]:::agent H3 --> H4["User provides name"]:::user H4 --> H5["Bot asks for email"]:::agent H5 --> H6["User provides email"]:::user H6 --> H7{"User wants
to share
phone?"}:::agent H7 -- Yes --> H8["User provides phone"]:::user H7 -- No --> H9["Phone marked
'(not shared)'"]:::agent H8 --> H10["Bot confirms details
with summary"]:::agent H9 --> H10 H10 --> H11["Save visitor info
to chat log meta
(name, email, phone)"]:::log H11 --> H12["Update chat log status
→ 'handoff'"]:::log H2 -- Yes --> H13["Bot says team will
follow up with new question"]:::agent H13 --> H12 H12 --> H14["Query available agents
from julian_chat_agent CPT
ordered by menu_order"]:::agent H14 --> H15{"Agents
available?"}:::agent H15 -- None --> H16["No agent assigned
Email goes to
handoff email (Settings)"]:::agent H15 -- 1+ available --> H17["Assign agent via
round-robin queue
(next in order)"]:::agent H17 --> H18["Save assigned agent ID
to chat log post meta
'_assigned_agent'"]:::log H16 --> H19["Send handoff email
via wp_mail()"]:::agent H18 --> H19 H19 --> H20{"Agent email
notification
enabled?"}:::agent H20 -- Yes --> H21["Email sent to assigned agent
Subject: 'New Chat Assigned'
Body: visitor name, email, phone,
transcript link, contact ASAP"]:::agent H20 -- No --> H22["Skip agent email"]:::agent H22 --> H23{"Visitor email
confirmation
enabled?"}:::agent H21 --> H23 H23 -- Yes --> H24["Email sent to visitor
'Thank you for contacting SLTC.
Our team will reach out within 2 days.'"]:::agent H23 -- No --> H25["Skip visitor email"]:::agent H24 --> H26["Bot tells user:
'Our team will contact you soon'"]:::agent H25 --> H26 H26 --> H27["Chat log updated:
status=handoff, agent assigned,
transcript saved, emails logged"]:::log H27 --> H28["Chat Logs admin shows
assigned agent name + avatar"]:::admin classDef ai fill:#1a0a2e,stroke:#a855f7,color:#c084fc classDef agent fill:#2a1a0a,stroke:#f97316,color:#fdba74 classDef user fill:#0a1f0e,stroke:#22c55e,color:#86efac classDef log fill:#2a0e0e,stroke:#ef4444,color:#fca5a5 classDef admin fill:#1e1a0e,stroke:#d4a017,color:#f0c040

flowchart TD L1["Every message exchange"]:::log --> L2["Chat log post created/updated
CPT: julian_chat_log (private)"]:::log L2 --> L3["Post title: Session ID + date"]:::log L2 --> L4["Post meta stored:
_session_id, _visitor_ip,
_visitor_name, _visitor_email,
_visitor_phone, _chat_status,
_assigned_agent, _feedback_up,
_feedback_down, _message_count"]:::log L2 --> L5["Post content:
Full JSON transcript
(wp_slash + JSON_UNESCAPED_UNICODE
so emojis & newlines preserved)"]:::log L5 --> L6["Admin Chat Logs view"]:::admin L6 --> L7["Table columns:
Session · Visitor · Status
Agent (name + avatar) · Feedback
Messages · Date"]:::admin L6 --> L8["Click → Modal transcript
Full message history with
bot/user bubbles, timestamps,
feedback badges, comments"]:::admin L6 --> L9["Filter by:
Status (bot/handoff)
Assigned agent
Date range"]:::admin L4 --> L10["Dashboard stat cards
read from meta queries:
COUNT handoffs, today's chats,
feedback totals"]:::admin L2 --> L11{"Daily cron
runs"}:::system L11 --> L12["Delete chat logs
older than 30 days"]:::system classDef log fill:#2a0e0e,stroke:#ef4444,color:#fca5a5 classDef admin fill:#1e1a0e,stroke:#d4a017,color:#f0c040 classDef system fill:#1a2332,stroke:#3b82f6,color:#93c5fd

flowchart LR IE1["Admin: KB List page"]:::admin IE1 --> EXP["Export"]:::admin EXP --> EXP1["Choose format:
XML / CSV / JSON"]:::admin EXP1 --> EXP2["All KB entries queried
from julian_chat_kb CPT"]:::log EXP2 --> EXP3["File generated &
downloaded to browser"]:::admin IE1 --> IMP["Import"]:::admin IMP --> IMP1["Upload file:
XML / CSV / JSON"]:::admin IMP1 --> IMP2["Parse file content"]:::system IMP2 --> IMP3{"Duplicate
handling mode?"}:::system IMP3 -- Skip --> IMP4["Skip entries that
already exist (by title)"]:::system IMP3 -- Overwrite --> IMP5["Update existing entries
with new content"]:::system IMP4 --> IMP6["Import result:
X added, Y skipped,
Z errors"]:::admin IMP5 --> IMP6 classDef admin fill:#1e1a0e,stroke:#d4a017,color:#f0c040 classDef log fill:#2a0e0e,stroke:#ef4444,color:#fca5a5 classDef system fill:#1a2332,stroke:#3b82f6,color:#93c5fd

flowchart TD M1["Plugin Activation
Register CPTs + Cron"]:::system M1 --> M2["Admin Configures
API Key + Settings + KB"]:::admin M2 --> M3["Admin Creates Agents
(name, email, phone, avatar)"]:::agent M3 --> M4["Visitor Opens Chat
Voice intro + orb"]:::user M4 --> M5["User Sends Message"]:::user M5 --> M6["Server: Rate Limit +
KB Retrieval + Gemini API"]:::ai M6 --> M7{"[HANDOFF]?"}:::ai M7 -- No --> M8["Bot responds
with KB context"]:::ai M8 --> M9["User rates
thumbs up/down"]:::user M9 --> M10["Save to Chat Log
+ Feedback meta"]:::log M10 --> M5 M7 -- Yes --> M11["Collect visitor
name + email + phone"]:::agent M11 --> M12["Assign agent
(round-robin queue)"]:::agent M12 --> M13{"Notifications
enabled?"}:::agent M13 -- Yes --> M14["Email agent:
'New chat assigned'"]:::agent M13 -- Yes --> M15["Email visitor:
'SLTC will contact
within 2 days'"]:::agent M14 --> M16["Update chat log:
status=handoff,
agent=assigned"]:::log M15 --> M16 M13 -- No --> M16 M16 --> M17["Admin views in
Chat Logs with
agent + transcript"]:::admin M10 --> M18["Daily cron:
purge logs >30 days"]:::system M16 --> M18 classDef system fill:#1a2332,stroke:#3b82f6,color:#93c5fd classDef admin fill:#1e1a0e,stroke:#d4a017,color:#f0c040 classDef agent fill:#2a1a0a,stroke:#f97316,color:#fdba74 classDef user fill:#0a1f0e,stroke:#22c55e,color:#86efac classDef ai fill:#1a0a2e,stroke:#a855f7,color:#c084fc classDef log fill:#2a0e0e,stroke:#ef4444,color:#fca5a5