# last-dance-collective/chatboxd architecture

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

- Interactive diagram: https://gitdiagram.com/last-dance-collective/chatboxd
- Repository: https://github.com/last-dance-collective/chatboxd

## Overview

##### Project type and purpose
- Project type: Full-stack web application with a single-page UI (Streamlit) that leverages Large Language Models (via LangChain/LangGraph) to query and analyze user movie data from Letterboxd.
- Purpose: Enable chat-based exploration of a user’s Letterboxd data (reviews, diary entries) and external movie details, using LLM agents and custom “tools.”

##### File structure
- src/main.py → Entry point for Streamlit UI.
- src/config.py + src/enviroment_config.py → Application configuration.
- src/data_ingestion/ → Batch script to load and transform CSV exports into SQLite (letterboxd.db).
- src/services/ → Definitions of agent “tools” and services: LLM interface, graph generation, database access, movie-data retrieval.
- src/catalog/ → Prompt templates, styles, translations for chat UI.
- src/utils/ → Helper modules (file loaders, session, logging, LLM/agent utilities).
- letterboxd.db → SQLite database.

##### Extract architectural insights from the README
- Core components: Streamlit frontend, SQLite database, ReAct agent built on LangChain/LangGraph, external services (OpenAI/Ollama, OMDb API).
- Agent pattern: Filter → Reason → Act → Observe loop, invoking “tools” to query DB or external APIs.
- Data ingestion pipeline: CSV → sqlite_utils → populated tables (reviews, diary) with E/R model.

a. Frontend (Streamlit UI)
- Hosts chat interface, renders graphs/images, collects user input.
- Calls backend Python functions via Streamlit’s process.
b. Application Layer / Agent Orchestrator
- LangChain/LangGraph orchestrator module sits here.
- Implements Filter → Agent (ReAct) loop, dispatches tool calls.
- Modules: llm_service (OpenAI/Ollama client), langgraph_service, agent_tools.
c. Tools/Services
- get_movies, get_reviews, get_graph, get_movie_details(extended).
- graph_services (generates network/visual graph).
- movies_data_service (OMDb fallback).
- sqlite_service (CRUD interface to letterboxd.db).
d. Data Layer
- SQLite database (reviews, diary tables).
- Data ingestion pipeline (data_ingestion/main.py, sqlite_utils).
e. External Services
- OpenAI API (chat/completion).
- OMDb API (movie metadata).
- (Optionally) Ollama local LLM endpoint.

##### Relationships and data flows
- User ↔ Streamlit UI: enters query / displays response.
- Streamlit UI → Agent Orchestrator: passes user message.
- Agent Orchestrator → llm_service: obtains next action (e.g., call tool).
- Agent Orchestrator → Tools → Data Layer or External Services.
- Tool outputs → Agent Orchestrator → llm_service (observe) → final response.
- Data Ingestion: separate offline pipeline that populates SQLite (one-way).

##### Architectural patterns and tech stack
- ReAct Agent Pattern (chain of thought + tool use).
- Modular “services” layer separating domain logic (DB, graph, API).
- Single-process Streamlit UI with embedded Python backend.
- SQLite as embedded relational DB for portability.
- LangChain & LangGraph for LLM orchestration.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User
    User["User"]:::external

    %% Frontend
    Streamlit["Streamlit Frontend"]:::frontend
    click Streamlit "https://github.com/last-dance-collective/chatboxd/blob/main/src/main.py"

    %% Configuration
    subgraph "Configuration"
        ConfigPY["config.py"]:::config
        EnvConfig["environment_config.py"]:::config
        StreamlitConfig[".streamlit/config.toml"]:::config
        click ConfigPY "https://github.com/last-dance-collective/chatboxd/blob/main/src/config.py"
        click EnvConfig "https://github.com/last-dance-collective/chatboxd/blob/main/src/enviroment_config.py"
        click StreamlitConfig "https://github.com/last-dance-collective/chatboxd/blob/main/.streamlit/config.toml"
    end

    %% Catalog
    subgraph "UI Catalog" 
        Prompts["prompts.py"]:::catalog
        Styles["styles.py"]:::catalog
        Translations["translations.py"]:::catalog
        click Prompts "https://github.com/last-dance-collective/chatboxd/blob/main/src/catalog/prompts.py"
        click Styles "https://github.com/last-dance-collective/chatboxd/blob/main/src/catalog/styles.py"
        click Translations "https://github.com/last-dance-collective/chatboxd/blob/main/src/catalog/translations.py"
    end

    %% Utilities
    subgraph "Utils"
        AgentUtils["agent_utils.py"]:::utils
        ChatUtils["chat_utils.py"]:::utils
        FileLoader["file_loader_utils.py"]:::utils
        FrameUtils["frame_utils.py"]:::utils
        InitUtils["init_utils.py"]:::utils
        LangGraphUtils["langgraph_utils.py"]:::utils
        LoggerUtils["logger_utils.py"]:::utils
        SessionUtils["session_utils.py"]:::utils
        click AgentUtils "https://github.com/last-dance-collective/chatboxd/blob/main/src/utils/agent_utils.py"
        click ChatUtils "https://github.com/last-dance-collective/chatboxd/blob/main/src/utils/chat_utils.py"
        click FileLoader "https://github.com/last-dance-collective/chatboxd/blob/main/src/utils/file_loader_utils.py"
        click FrameUtils "https://github.com/last-dance-collective/chatboxd/blob/main/src/utils/frame_utils.py"
        click InitUtils "https://github.com/last-dance-collective/chatboxd/blob/main/src/utils/init_utils.py"
        click LangGraphUtils "https://github.com/last-dance-collective/chatboxd/blob/main/src/utils/langgraph_utils.py"
        click LoggerUtils "https://github.com/last-dance-collective/chatboxd/blob/main/src/utils/logger_utils.py"
        click SessionUtils "https://github.com/last-dance-collective/chatboxd/blob/main/src/utils/session_utils.py"
    end

    %% Data Ingestion Pipeline
    subgraph "Data Ingestion Pipeline"
        DataIngestMain["Batch Loader"]:::service
        SqliteUtils["SQLite Utilities"]:::service
        DiaryCSV["diary.csv"]:::database
        ReviewsCSV["reviews.csv"]:::database
        click DataIngestMain "https://github.com/last-dance-collective/chatboxd/blob/main/src/data_ingestion/main.py"
        click SqliteUtils "https://github.com/last-dance-collective/chatboxd/blob/main/src/data_ingestion/sqlite_utils.py"
    end

    DiaryCSV -.->|ingest| DataIngestMain
    ReviewsCSV -.->|ingest| DataIngestMain
    DataIngestMain -.->|transforms| SqliteUtils
    SqliteUtils -.->|populates| Database

    %% Database
    Database["SQLite Database<br/>(letterboxd.db)"]:::database
    click Database "https://github.com/last-dance-collective/chatboxd/blob/main/letterboxd.db"

    %% External Services
    OpenAI["OpenAI API"]:::external
    OMDb["OMDb API"]:::external
    Ollama["Ollama LLM"]:::external

    %% Application Layer
    subgraph "Application / Agent Layer"
        Orchestrator["LangChain Agent Orchestrator"]:::service
        LLMService["LLM Interface Service"]:::service
        click Orchestrator "https://github.com/last-dance-collective/chatboxd/blob/main/src/services/langgraph_service.py"
        click LLMService "https://github.com/last-dance-collective/chatboxd/blob/main/src/services/llm_service.py"
    end

    %% Tools / Services
    subgraph "Service Modules" 
        AgentTools["Agent Tools Module"]:::service
        GraphService["Graph Generation Service"]:::service
        MoviesService["Movie Details Service"]:::service
        SQLiteService["SQLite CRUD Service"]:::service
        DailyMessage["Daily Message Service"]:::service
        click AgentTools "https://github.com/last-dance-collective/chatboxd/blob/main/src/services/agent_tools.py"
        click GraphService "https://github.com/last-dance-collective/chatboxd/blob/main/src/services/graph_services.py"
        click MoviesService "https://github.com/last-dance-collective/chatboxd/blob/main/src/services/movies_data_service.py"
        click SQLiteService "https://github.com/last-dance-collective/chatboxd/blob/main/src/services/sqlite_service.py"
        click DailyMessage "https://github.com/last-dance-collective/chatboxd/blob/main/src/services/daily_message_service.py"
    end

    %% Flows
    User -->|inputs query| Streamlit
    Streamlit -->|loads config| ConfigPY
    Streamlit -->|uses catalog| Prompts
    Streamlit -->|calls| Orchestrator
    Orchestrator -->|asks| LLMService
    Orchestrator -->|dispatches tool| AgentTools
    AgentTools -->|uses| SQLiteService
    AgentTools -->|uses| MoviesService
    AgentTools -->|uses| GraphService
    AgentTools -->|uses| DailyMessage
    SQLiteService -->|queries| Database
    MoviesService -->|fetches| OMDb
    LLMService -->|API call| OpenAI
    LLMService -->|API call| Ollama

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef service fill:#E6F4EA,stroke:#22863A,color:#22863A;
    classDef database fill:#FFF5B1,stroke:#E7A000,color:#E7A000,shape:cylinder;
    classDef external fill:#FFEBE9,stroke:#D73A49,color:#D73A49,shape:cloud;
    classDef utils fill:#F5F0FF,stroke:#6F42C1,color:#6F42C1;
    classDef catalog fill:#FFFAEC,stroke:#735C0F,color:#735C0F;
    classDef config fill:#E6F0FA,stroke:#1E40AF,color:#1E40AF;
```
