# spider-hand/advanced-chat-kai architecture

> Architecture diagram of the GitHub repository spider-hand/advanced-chat-kai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spider-hand/advanced-chat-kai
- Repository: https://github.com/spider-hand/advanced-chat-kai

## Overview

##### Project Type and Purpose
- This is an open-source, framework-agnostic Web Component library named advanced-chat-kai.
- Its primary goal is to provide a highly customizable chat UI that any host application (Vue, React, plain HTML, etc.) can integrate by passing in data and listening to events.

##### File Structure Analysis
- **Top-level folders and files**
- `.github/workflows`: CI/CD pipelines for testing, bundle-size analysis, and releases
- `src`: Core library code, including Lit-based components, context management, styles, and type definitions
- `demo`: A standalone Vite+Vue demo application showcasing component usage
- `stories`: Storybook stories for visual testing and documentation
- `test/unit`: Vitest unit tests for individual components
- Config/build files: `vite.config.ts`, `tsconfig*.json`, `rollup` (implicit via package.json), `storybook` config
- **Patterns**
- Component-driven architecture: one file per UI subcomponent in `src/components`
- Contexts (`src/contexts`) and constants (`src/consts`) for shared state/internationalization
- Logic-free approach: UI rendering only; all business logic, data fetching, and state lives in the host

##### Key Architectural Elements from README
- **Reactive Inputs**: library exposes many props for rooms, messages, attachments, suggestions, theming, etc.
- **Event-based Outputs**: component emits events (e.g. `send-message`, `select-room`) for the host to handle
- **Build & Delivery**: published to npm; bundle optimized for minimal size (Lit, ES modules)
- **Customization**: theming via CSS custom properties; Shadow DOM encapsulation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Application
    subgraph "Host Application"
        HostApp["Host Application"]:::host
    end

    %% Library Container
    subgraph "advanced-chat-kai" 
        direction TB
        Root["advanced-chat-kai Root Component"]:::lib

        subgraph "Context Providers"
            direction TB
            I18n["i18n Context"]:::context
            CurrentUser["Current User Context"]:::context
            RoomCtx["Room Context"]:::context
            MsgCtx["Message Context"]:::context
            FooterCtx["Footer Context"]:::context
            SidebarCtx["Sidebar Context"]:::context
        end

        subgraph "UI Components"
            direction TB
            Sidebar["Sidebar"]:::lib
            Header["Chat Header"]:::lib
            MsgList["Message List"]:::lib

            subgraph "Message List Components"
                direction TB
                MsgItem["Message Item"]:::lib
                Divider["Message Divider"]:::lib
                AttachList["Message Attachment List"]:::lib
                ReactionList["Message Reaction List"]:::lib
                Typing["Message Typing Indicator"]:::lib
            end

            Footer["Chat Footer"]:::lib

            subgraph "Footer Components"
                direction TB
                FooterAttach["Footer Attachment Section"]:::lib
                FooterReply["Footer Reply-To Section"]:::lib
                EmojiPicker["Emoji Picker"]:::lib
            end

            Dialog["Dialog Overlay"]:::lib

            subgraph "Sidebar Components"
                direction TB
                RoomList["Room List"]:::lib
                RoomItem["Room Item"]:::lib
                SearchInput["Search Input"]:::lib
                ActionList["Action List"]:::lib
                NotificationBadge["Notification Badge"]:::lib
            end

            Avatar["Avatar Component"]:::lib
            SuggestionList["Suggestion List"]:::lib
            Loader["Loader (spinner)"]:::lib
            DeletedMsg["Deleted Message Display"]:::lib
        end
    end

    %% CI/CD and Documentation
    subgraph "CI/CD & Docs"
        direction TB
        GitHubActions["GitHub Actions"]:::ci
        Storybook["Storybook"]:::docs
        Vitest["Vitest Tests"]:::docs
        npm["npm Registry"]:::external
    end

    %% Data & Event Flow
    HostApp -->|"props"| Root
    Root -->|"events"| HostApp
    Root --> Sidebar
    Root --> Header
    Root --> MsgList
    Root --> Footer
    Root --> Dialog

    I18n --> Root
    CurrentUser --> Root
    RoomCtx --> Root
    MsgCtx --> Root
    FooterCtx --> Root
    SidebarCtx --> Root

    MsgList --> MsgItem
    MsgList --> Divider
    MsgList --> AttachList
    MsgList --> ReactionList
    MsgList --> Typing

    Footer --> FooterAttach
    Footer --> FooterReply
    Footer --> EmojiPicker

    Sidebar --> RoomList
    Sidebar --> SearchInput
    Sidebar --> ActionList
    Sidebar --> NotificationBadge
    RoomList --> RoomItem

    Root --> Avatar
    Root --> SuggestionList
    Root --> Loader
    Root --> DeletedMsg

    GitHubActions -.->|build/test/release| npm
    Storybook -.-> advanced-chat-kai
    Vitest -.-> advanced-chat-kai

    %% Click Events
    click Root "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/advanced-chat-kai.ts"
    click Sidebar "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-sidebar.ts"
    click Header "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-header.ts"
    click MsgList "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-message-list.ts"
    click MsgItem "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-message-item.ts"
    click Divider "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-message-divider.ts"
    click AttachList "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-message-attachment-list.ts"
    click ReactionList "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-message-reaction-list.ts"
    click Typing "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-message-typing.ts"
    click Footer "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-footer.ts"
    click FooterAttach "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-footer-attachment-section.ts"
    click FooterReply "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-footer-reply-to-section.ts"
    click Dialog "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-dialog.ts"
    click EmojiPicker "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-emoji-picker.ts"
    click ActionList "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-action-list.ts"
    click Avatar "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-avatar.ts"
    click RoomList "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-room-list.ts"
    click RoomItem "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-room-item.ts"
    click SearchInput "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-search.ts"
    click SuggestionList "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-suggestion-list.ts"
    click NotificationBadge "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-notification-badge.ts"
    click Loader "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-loader.ts"
    click DeletedMsg "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/components/chat-deleted-message.ts"
    click I18n "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/contexts/i18n-context.ts"
    click CurrentUser "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/contexts/current-user-id-context.ts"
    click RoomCtx "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/contexts/room-context.ts"
    click MsgCtx "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/contexts/message-context.ts"
    click FooterCtx "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/contexts/footer-context.ts"
    click SidebarCtx "https://github.com/spider-hand/advanced-chat-kai/blob/main/src/contexts/sidebar-context.ts"

    %% Styles
    classDef lib fill:#D0E8FF,stroke:#0366d6;
    classDef host fill:#DFFFD0,stroke:#228B22;
    classDef context fill:#FFF4D0,stroke:#DAA520;
    classDef external fill:#E0E0E0,stroke:#888888;
    classDef ci fill:#FFE0D0,stroke:#FF8C00;
    classDef docs fill:#E8D0FF,stroke:#800080;
```
