# sachinkallar/ai_chat_app architecture

> Architecture diagram of the GitHub repository sachinkallar/ai_chat_app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sachinkallar/ai_chat_app
- Repository: https://github.com/sachinkallar/ai_chat_app

## Overview

##### What this project is (type + purpose)
This is a **client-only Flutter Web application** that renders an AI chat UI in the browser and calls an **external LLM inference endpoint** (Fireworks AI / Hugging Face router) via HTTPS. There is **no backend service in this repo**—the “server-side” is the external inference API.

Key indicators:
- `lib/` contains Flutter app code (widgets/screens/providers/services).
- `web/index.html` + `web/manifest.json` indicates Flutter Web + PWA-style manifest.
- `lib/services/huggingface_service.dart` implies direct HTTP integration from the browser to the inference API.
- README explicitly states Fireworks AI Inference API + Hugging Face router endpoint.

- **Browser runtime** (Flutter compiled to JS/CanvasKit) as the execution environment
- **Local state management** (Provider)
- **External API dependency** (Fireworks/HF endpoint)
- **API key handling** (in-memory, non-persistent)

##### How to read the file structure (what maps to architecture)

Architecturally relevant directories:
- `lib/main.dart` — app entry point; wires up root widget(s), providers, theme, routes.
- `lib/screens/chat_screen.dart` — main UI container (chat page).
- `lib/widgets/`:
- `api_key_dialog.dart` — API key capture UI (settings flow).
- `message_bubble.dart` — rendering of user/assistant messages.
- `lib/models/chat_message.dart` — domain model: message structure (role/content/timestamp/etc.).
- `lib/providers/chat_provider.dart` — state + orchestration: list of messages, loading indicator, calling service, clearing chat.
- `lib/services/huggingface_service.dart` — integration boundary: constructs HTTP request, sets headers (API key), parses response/errors.
- `web/index.html` — web bootstrap (loads compiled Flutter bundle).

This structure strongly suggests a classic Flutter layering:
**UI (screens/widgets) → State (provider) → Service (HTTP client) → External API**.

Goal: show who uses it and what it depends on.
Include:
- **User** (human)
- **Browser** (Chrome/Firefox/etc.)
- **AI Chat App (Flutter Web)** (this system)
- **Fireworks AI / Hugging Face Router Inference API** (external system)
- (Optional) **Public Internet / HTTPS** boundary

- User ↔ AI Chat App (UI interactions)
- AI Chat App → External Inference API (HTTPS REST: `/v1/chat/completions`)
- External API → AI Chat App (chat completion response)

A **trust boundary** around the browser: the API key is entered in the browser and sent to the external API; there is no server to “hide” secrets.

Goal: show runtime containers and deployable units.
In this project, containers are minimal:
- **Static Hosting / Origin** (optional, but realistic in production): serves `index.html`, compiled JS, assets
- **Web Browser Container**:
- Flutter Web runtime (compiled Dart → JS)
- Local memory state (Provider state)
- **External LLM API**:
- Fireworks/HF router endpoint
- Model backend (SmolLM3-3B or configured model)

Goal: map code structure to runtime responsibilities (what talks to what).
Use the code directories almost 1:1 as components:

**UI Layer**
- `ChatScreen` (lib/screens/chat_screen.dart)
- `MessageBubble` (lib/widgets/message_bubble.dart)
- `ApiKeyDialog` (lib/widgets/api_key_dialog.dart)

**State/Domain Layer**
- `ChatProvider` (lib/providers/chat_provider.dart)
- `ChatMessage` model (lib/models/chat_message.dart)

**Integration Layer**
- `HuggingFaceService` (lib/services/huggingface_service.dart)
- `http` package (dependency; can be shown as “HTTP Client”)

**External**
- Fireworks AI / HF Router Inference API

- `ChatScreen` → `ChatProvider` (subscribes to state; dispatches send/clear/setKey actions)
- `ChatProvider` → `HuggingFaceService` (requests completion)
- `HuggingFaceService` → External API (HTTPS)
- `ChatProvider` ↔ `ChatMessage` (creates/updates message list)
- `ChatScreen` → `MessageBubble` (renders each message)
- `ChatScreen` → `ApiKeyDialog` (collect key; passes to provider)

Important internal flows:
- API key is stored in **provider state** (per README: not persisted between sessions)
- Loading indicator is driven by provider state (request in-flight)

Goal: show the exact chat request lifecycle.
A typical sequence:
##### External API returns completion JSON (or error)
7. `ChatProvider` appends assistant `ChatMessage` (or error message), sets `isLoading=false`, notifies listeners

##### Main components
- **Client/UI (Flutter Web)**: `main.dart` root + `ChatScreen` + widgets
- **State management**: `ChatProvider` (Provider package)
- **Domain model**: `ChatMessage`
- **HTTP integration**: `HuggingFaceService` using `http`
- **External inference service**: Fireworks AI / Hugging Face router endpoint
- **(Optional)** Static hosting / CDN that serves the app

##### Core interactions (data flows)
- **User input → Provider action**: message text + send event
- **Provider → Service**: message history + config (model/params) + API key
- **Service → External API**: HTTPS POST
- **External API → Service → Provider**: completion response
- **Provider → UI**: state updates (messages list, loading flag, errors)
- **API key flow**: ApiKeyDialog → Provider (in-memory) → Service (Authorization header)

##### Architectural pattern to call out
- **Presentation + state container + service adapter** pattern (common Flutter architecture)
- **Unidirectional-ish data flow**: UI dispatches intents; Provider mutates state; UI reacts via listeners
- **Externalized inference**: no local model; everything is remote API call

##### Sequence (send message → completion → render)

This approach captures the essential architecture with high fidelity to the repo structure, without inventing nonexistent backend infrastructure.

- `lib/main.dart` → “App bootstrap / Provider wiring / Theme”
- `lib/screens/chat_screen.dart` → “Chat UI screen”
- `lib/widgets/message_bubble.dart` → “Message renderer”
- `lib/widgets/api_key_dialog.dart` → “API Key input / settings”
- `lib/providers/chat_provider.dart` → “Chat state + orchestration”
- `lib/models/chat_message.dart` → “Message domain model”
- `lib/services/huggingface_service.dart` → “Inference API client adapter”
- `web/index.html` → “Web entry / loads Flutter bundle”
- `web/manifest.json` → “PWA metadata”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =======================
    %% Panel A — System Context (C4 L1)
    %% =======================
    subgraph "A. System Context (C4 L1)"
        direction TB
        User(["User (Human)"]):::external

        subgraph "Browser Trust Boundary (API key exists here)"
            direction TB
            Browser["Web Browser (Chrome/Firefox)"]:::container
            App["AI Chat App (Flutter Web)"]:::system
            KeyNote["Note: API key entered client-side\nStored in-memory (not persisted)"]:::note
        end

        ExternalAPI(["Fireworks AI / HF Router\nChat Completions API"]):::external
        Internet["Public Internet (HTTPS)"]:::infra

        User -->|"typesMessage/clicksSend"| App
        App -->|"rendersUI"| Browser

        App -->|"HTTPS_POST_/v1/chat/completions"| Internet
        Internet -->|"routesTo"| ExternalAPI
        ExternalAPI -->|"completionJSON_or_error"| Internet
        Internet -->|"HTTPS_response"| App

        KeyNote -.->|"trustBoundaryNote"| Browser
    end

    %% =======================
    %% Panel B — Container Diagram (C4 L2)
    %% =======================
    subgraph "B. Containers (C4 L2)"
        direction TB

        StaticHost["Static Hosting / Origin (serves assets)"]:::infra
        WebIndex["web/index.html (bootstrap)"]:::artifact
        WebManifest["web/manifest.json (PWA metadata)"]:::artifact

        subgraph "Web Browser Container"
            direction TB
            FlutterRuntime["Flutter Web Runtime (Dart→JS/CanvasKit)"]:::container
            InMemoryState["Local Memory State (Provider)"]:::state
        end

        ExtLLM["External LLM Inference Service\n(Fireworks/HF Router)"]:::external

        StaticHost -->|"serves"| WebIndex
        StaticHost -->|"serves"| WebManifest
        WebIndex -->|"loadsFlutterBundle"| FlutterRuntime
        FlutterRuntime -->|"managesState"| InMemoryState
        FlutterRuntime -->|"HTTPS_calls"| ExtLLM
        ExtLLM -->|"responses"| FlutterRuntime
    end

    %% =======================
    %% Panel C — Component Diagram (C4 L3, repo mapping)
    %% =======================
    subgraph "C. Components (C4 L3 — lib/ + web/ mapping)"
        direction TB

        subgraph "Web Bootstrap (web/)"
            direction TB
            WebIndex2["Web Entry (index.html)"]:::artifact
            WebManifest2["PWA Manifest (manifest.json)"]:::artifact
        end

        subgraph "App Bootstrap"
            direction TB
            MainDart["App bootstrap / Provider wiring / Theme (main.dart)"]:::bootstrap
        end

        subgraph "UI Layer (screens/widgets)"
            direction TB
            ChatScreen["Chat UI Screen (ChatScreen)"]:::ui
            ApiKeyDialog["API Key Input Dialog (ApiKeyDialog)"]:::ui
            MessageBubble["Message Renderer (MessageBubble)"]:::ui
            LoadingNote["Note: loadingIndicator driven by provider state"]:::note
        end

        subgraph "State + Domain Layer"
            direction TB
            ChatProvider["Chat State + Orchestration (ChatProvider)"]:::state
            ChatMessage["Message Domain Model (ChatMessage)"]:::domain
            ApiKeyState["In-memory API key (not persisted)"]:::note
        end

        subgraph "Integration Layer"
            direction TB
            HuggingFaceService["Inference API Client Adapter (HuggingFaceService)"]:::service
            HttpClient["HTTP Client (package:http)"]:::service
        end

        subgraph "External Dependency"
            direction TB
            InferenceAPI["Fireworks AI / HF Router — Chat Completions API"]:::external
        end

        %% Bootstrap wiring
        WebIndex2 -->|"boots"| MainDart
        WebManifest2 -.->|"installableMetadata"| WebIndex2
        MainDart -->|"buildsRootWidget"| ChatScreen
        MainDart -->|"registersProvider"| ChatProvider

        %% UI -> Provider (intents)
        ChatScreen -->|"sendMessage(text)"| ChatProvider
        ChatScreen -->|"clearChat()"| ChatProvider
        ChatScreen -->|"openSettings"| ApiKeyDialog
        ApiKeyDialog -->|"setApiKey(key)"| ChatProvider

        %% UI composition
        ChatScreen -->|"rendersEachMessage"| MessageBubble
        LoadingNote -.->|"observes"| ChatScreen

        %% Provider <-> Domain
        ChatProvider -->|"creates/appends"| ChatMessage
        ChatProvider -->|"holdsList<ChatMessage>"| ChatMessage

        %% Provider -> Service -> External
        ChatProvider -->|"createChatCompletion(messages,params,apiKey)"| HuggingFaceService
        HuggingFaceService -->|"uses"| HttpClient
        HuggingFaceService -->|"HTTPS_POST_/v1/chat/completions"| InferenceAPI
        InferenceAPI -->|"completionJSON_or_error"| HuggingFaceService
        HuggingFaceService -->|"parsedResult"| ChatProvider

        %% Provider -> UI (notifications)
        ChatProvider -.->|"notifyListeners()"| ChatScreen

        %% Key handling note
        ApiKeyState -.->|"storedIn"| ChatProvider
        ChatProvider -.->|"passesAsAuthHeader"| HuggingFaceService
    end

    %% =======================
    %% Panel D — Runtime Sequence (rendered as flow steps)
    %% =======================
    subgraph "D. Runtime Sequence (Send Message → Completion)"
        direction TB

        S1["1) User enters text + Send (ChatScreen)"]:::sequence
        S2["2) ChatScreen → ChatProvider.sendMessage(text)"]:::sequence
        S3["3) ChatProvider appends user ChatMessage\nsets isLoading=true\nnotifyListeners()"]:::sequence
        S4["4) ChatProvider → HuggingFaceService.createChatCompletion(...)"]:::sequence
        S5["5) HuggingFaceService → External API\nHTTPS POST /v1/chat/completions\n(Authorization header uses API key)"]:::sequence
        S6["6) External API returns completion JSON (or error)"]:::sequence
        S7["7) ChatProvider appends assistant ChatMessage (or error)\nsets isLoading=false\nnotifyListeners()"]:::sequence
        S8["8) ChatScreen rebuilds\nMessageBubble list updates\nloading indicator cleared"]:::sequence

        S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8
    end

    %% =======================
    %% Click Events (from component_mapping)
    %% =======================
    click MainDart "https://github.com/sachinkallar/ai_chat_app/blob/main/lib/main.dart"
    click ChatScreen "https://github.com/sachinkallar/ai_chat_app/blob/main/lib/screens/chat_screen.dart"
    click MessageBubble "https://github.com/sachinkallar/ai_chat_app/blob/main/lib/widgets/message_bubble.dart"
    click ApiKeyDialog "https://github.com/sachinkallar/ai_chat_app/blob/main/lib/widgets/api_key_dialog.dart"
    click ChatProvider "https://github.com/sachinkallar/ai_chat_app/blob/main/lib/providers/chat_provider.dart"
    click ChatMessage "https://github.com/sachinkallar/ai_chat_app/blob/main/lib/models/chat_message.dart"
    click HuggingFaceService "https://github.com/sachinkallar/ai_chat_app/blob/main/lib/services/huggingface_service.dart"
    click WebIndex "https://github.com/sachinkallar/ai_chat_app/blob/main/web/index.html"
    click WebIndex2 "https://github.com/sachinkallar/ai_chat_app/blob/main/web/index.html"
    click WebManifest "https://github.com/sachinkallar/ai_chat_app/blob/main/web/manifest.json"
    click WebManifest2 "https://github.com/sachinkallar/ai_chat_app/blob/main/web/manifest.json"

    %% =======================
    %% Styles
    %% =======================
    classDef system fill:#1f77b4,stroke:#0b3d91,stroke-width:1px,color:#ffffff
    classDef ui fill:#4aa3ff,stroke:#1c5aa6,stroke-width:1px,color:#0b1b2b
    classDef bootstrap fill:#2b8cbe,stroke:#0b3d91,stroke-width:1px,color:#ffffff
    classDef state fill:#7b5cff,stroke:#3b2aa3,stroke-width:1px,color:#ffffff
    classDef domain fill:#b39cff,stroke:#5a46c6,stroke-width:1px,color:#1a1033
    classDef service fill:#ffb74d,stroke:#d17a00,stroke-width:1px,color:#3b2400
    classDef external fill:#bdbdbd,stroke:#616161,stroke-width:1px,color:#1b1b1b
    classDef infra fill:#90a4ae,stroke:#455a64,stroke-width:1px,color:#102027
    classDef container fill:#64b5f6,stroke:#1e88e5,stroke-width:1px,color:#0b1b2b
    classDef artifact fill:#a5d6a7,stroke:#2e7d32,stroke-width:1px,color:#0f2a12
    classDef note fill:#fff59d,stroke:#f9a825,stroke-width:1px,color:#3a2f00
    classDef sequence fill:#e3f2fd,stroke:#1e88e5,stroke-width:1px,color:#0b1b2b

    %% Emphasize trust boundary visually by styling inner nodes
    class User,ExternalAPI,ExtLLM,InferenceAPI external
    class App system
    class Browser,FlutterRuntime container
    class InMemoryState state
    class StaticHost,Internet infra
```
