# atbaker/dash architecture

> Architecture diagram of the GitHub repository atbaker/dash, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atbaker/dash
- Repository: https://github.com/atbaker/dash

## Overview

##### Project Type and Purpose
- DASH is a full-stack AI agent platform (“Executive AI Agent Platform”) composed of two main subsystems:
- agent/ (DigitalOcean Functions as HTTP microservices)
- chat/ (SvelteKit web chat frontend + FastAPI backend with optional Slack bot)
- Purpose: Provide a streaming chat UI and Slack interface that route user queries to a hosted AI agent (on DigitalOcean Gradient™), which in turn invokes specialized tool-functions (SQL queries, web search, Airtable operations) and an optional knowledge base.

##### File Structure Overview
Top-level directories:
- agent/
– functions/packages/gator/{run_sql_query, web_search, add_airtable_lead, list_airtable_leads, …}
– knowledge_base/ (CSV data files for P&L statements)
- chat/
– backend/ (FastAPI server, Slack integration, environment configs)
– src/ (SvelteKit files: routes, components, API client)
Configuration & orchestration:
- chat/docker-compose.yml, Dockerfile, .env examples, doctl deployment via agent/functions/project.yml

##### Key Insights from README
- HTTP-based microservice architecture
- DigitalOcean Functions host the business logic/tools
- FastAPI backend streams responses from the AI agent endpoint
- Slack Bot uses Slack Events API + FastAPI routes
- External integrations: Brave Search API, Airtable API, production or sample SQLite DB, DigitalOcean Knowledge Base

##### Diagramming the Architecture
a. Main Components
1. User Interfaces
– Web Chat (SvelteKit frontend)
– Slack Bot (via FastAPI backend)
2. Chat Backend (FastAPI)
– REST/WebSocket endpoints for frontend streaming
– Slack event handlers (slack_bot.py, chat_service.py)
3. DigitalOcean AI Agent
– Hosted on Gradient™; accepts user prompts and invokes tool routes
4. Functions (agent/functions)
– run_sql_query, web_search, add_airtable_lead, list_airtable_leads packages
– Each deployed as an HTTP endpoint via doctl
5. Knowledge Base (optional)
– DigitalOcean-hosted embeddings index (ingested from agent/knowledge_base CSVs)
6. External Services
– Airtable API
– Brave Search API
– Production database (or local SQLite sample)

b. Relationships & Data Flow
1. Web/App user → SvelteKit frontend → FastAPI streaming endpoint
2. Slack user → Slack platform → FastAPI Slack endpoint
3. FastAPI makes HTTP call → DO Agent endpoint (DO_AGENT_ENDPOINT)
4. DO Agent routes to:
- Knowledge Base (if configured)
- Functions via Function Routes (SQL, Search, Airtable)
5. Functions → External services (DB, APIs) → return JSON results
6. DO Agent composes final response → FastAPI → UI or Slack

c. Architectural Patterns & Principles
- Microservices for tool encapsulation
- Clear separation of concerns: UI, orchestration (FastAPI), business logic (Functions), persistence
- HTTP/REST and streaming (Server-Sent Events or WebSockets)
- Config-driven deployment (doctl, Docker Compose, environment variables)

d. Key Technologies & Frameworks
- Frontend: SvelteKit, Vite, Tailwind CSS
- Backend: Python 3.11+, FastAPI, uv package manager
- Serverless: DigitalOcean Functions with project.yml
- Data stores: SQLite (sample), Airtable, DigitalOcean Knowledge Base
- Integrations: Brave Search API, Slack API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        WebUI["Web Chat Frontend"]:::frontend
        Routes["Routes (+layout.svelte, +page.svelte)"]:::frontend
        Components["Components (*.svelte)"]:::frontend
        APIClient["API Client (chat.ts)"]:::frontend
        Stores["Stores (chat.ts)"]:::frontend
        SlackUI["Slack Interface"]:::frontend
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        FB["FastAPI Chat Backend"]:::backend
        FBConfig["Backend Config"]:::backend
        SlackBot["Slack Bot Integration"]:::backend
    end

    %% AI Agent
    AIAgent["DigitalOcean AI Agent\n(Gradient™)"]:::agent

    %% Serverless Functions
    subgraph "Serverless Functions"
        SQL["run_sql_query"]:::functions
        SEARCH["web_search"]:::functions
        ADD["add_airtable_lead"]:::functions
        LIST["list_airtable_leads"]:::functions
    end

    %% Data & External Services
    subgraph "Data & External Services"
        CSV["Knowledge Base (CSV)"]:::external
        Airtable["Airtable API"]:::external
        Brave["Brave Search API"]:::external
        DB["Production/SQLite DB"]:::external
    end

    %% Local Dev & Deployment Config
    DockerCompose["Docker Compose"]:::backend
    Dockerfile["Dockerfile"]:::backend
    FuncConfig["Functions Deployment Config"]:::backend
    EnvExamples["Env Examples"]:::backend

    %% Connections
    WebUI -->|HTTP/SSE| FB
    Routes --> WebUI
    Components --> WebUI
    APIClient --> WebUI
    Stores --> WebUI
    SlackUI -->|Slack Events API| SlackBot
    SlackBot -->|Invoke Chat| FB
    FB -->|HTTP JSON| AIAgent
    AIAgent -->|Invoke Tools| SQL
    AIAgent -->|Invoke Tools| SEARCH
    AIAgent -->|Invoke Tools| ADD
    AIAgent -->|Invoke Tools| LIST
    SQL -->|Query| DB
    SEARCH -->|Search| Brave
    ADD -->|Write| Airtable
    LIST -->|Read| Airtable
    CSV -->|Optional Lookup| AIAgent
    AIAgent -->|Stream Response| FB
    FB -->|Stream Response| WebUI
    FB -->|Stream Response| SlackUI
    DockerCompose --- FB
    Dockerfile --- WebUI
    Dockerfile --- FB
    FuncConfig --- SQL
    FuncConfig --- SEARCH
    EnvExamples --- FuncConfig
    EnvExamples --- FBConfig

    %% Click Events
    click SQL "https://github.com/atbaker/dash/tree/main/agent/functions/packages/gator/run_sql_query"
    click SEARCH "https://github.com/atbaker/dash/tree/main/agent/functions/packages/gator/web_search"
    click ADD "https://github.com/atbaker/dash/tree/main/agent/functions/packages/gator/add_airtable_lead"
    click LIST "https://github.com/atbaker/dash/tree/main/agent/functions/packages/gator/list_airtable_leads"
    click CSV "https://github.com/atbaker/dash/blob/main/agent/knowledge_base/*.csv"
    click FB "https://github.com/atbaker/dash/blob/main/chat/backend/main.py"
    click FB "https://github.com/atbaker/dash/blob/main/chat/backend/chat_service.py"
    click FBConfig "https://github.com/atbaker/dash/blob/main/chat/backend/pyproject.toml"
    click FBConfig "https://github.com/atbaker/dash/blob/main/chat/backend/.env.example"
    click SlackBot "https://github.com/atbaker/dash/blob/main/chat/backend/slack_bot.py"
    click Routes "https://github.com/atbaker/dash/blob/main/chat/src/routes/+layout.svelte"
    click Routes "https://github.com/atbaker/dash/blob/main/chat/src/routes/+page.svelte"
    click Components "https://github.com/atbaker/dash/tree/main/chat/src/lib/components/"
    click APIClient "https://github.com/atbaker/dash/blob/main/chat/src/lib/api/chat.ts"
    click Stores "https://github.com/atbaker/dash/blob/main/chat/src/lib/stores/chat.ts"
    click DockerCompose "https://github.com/atbaker/dash/blob/main/chat/docker-compose.yml"
    click Dockerfile "https://github.com/atbaker/dash/tree/main/chat/Dockerfile"
    click FuncConfig "https://github.com/atbaker/dash/blob/main/agent/functions/project.yml"
    click EnvExamples "https://github.com/atbaker/dash/blob/main/agent/functions/.env.example"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6
    classDef backend fill:#DFF6DD,stroke:#22863A
    classDef agent fill:#FFF5B1,stroke:#C08400
    classDef functions fill:#FFEFE0,stroke:#D17D11
    classDef external fill:#F0F0F0,stroke:#666
```
