# muhammadhassaanarain/dictionary-agent architecture

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

- Interactive diagram: https://gitdiagram.com/muhammadhassaanarain/dictionary-agent
- Repository: https://github.com/muhammadhassaanarain/dictionary-agent

## Overview

##### Project type and purpose
- This is a conversational AI application built on Chainlit (a Python-based chat UI framework).
- It provides a chat interface (frontend served by Chainlit), orchestrates an AI “agent” (agent.py) with guardrails (guardrails.py), optional tool execution (tools/tools.py), and logs conversations to a SQLite database (conversation.db).

##### File structure
- **.chainlit/**: Configuration for the Chainlit UI (config.toml) and translation files (i18n).
- **main.py**: Entrypoint that launches the Chainlit server and wires up the agent, guardrails, database, and tools.
- **agent.py**: Defines the AI agent’s logic and how it calls the LLM or other subcomponents.
- **guardrails.py**: Implements safety checks or structured schema enforcement around user messages or agent responses.
- **tools/tools.py**: Implements auxiliary functions the agent may invoke (e.g., data lookups, calculators).
- **configuration.py**: Centralizes loading of API keys, model choices, database paths, etc.
- **conversation.db** (+ WAL/SHM): SQLite database storing message history.
- **chainlit.md**: Documentation for Chainlit-specific behavior.
- **pyproject.toml**/uv.lock/**.python-version**: Dependency and environment specs.

##### (empty) README
- No additional architectural notes—so we infer primarily from code and file names.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Interface"
        User["User's Browser"]:::primary
    end

    subgraph "Backend"
        subgraph "Chainlit Server"
            CL_main["main.py"]:::primary
            CL_conf[".chainlit/config.toml"]:::primary
            Translations[".chainlit/translations/"]:::primary
        end

        Chainlit["Chainlit Server"]:::primary
        Agent["AI Agent\n(agent.py)"]:::primary
        Guardrails["Guardrails Module\n(guardrails.py)"]:::primary
        Tools["Tools Module\n(tools/tools.py)"]:::primary
        Config["Configuration Loader\n(configuration.py)"]:::doc
        subgraph "Conversation Database"
            DB["conversation.db"]:::db
            DB_shm["conversation.db-shm"]:::db
            DB_wal["conversation.db-wal"]:::db
        end
        LLM["External LLM API"]:::cloud
    end

    subgraph "Docs & Specs"
        Docs["chainlit.md"]:::doc
        PyProj["pyproject.toml"]:::doc
        UvLock["uv.lock"]:::doc
        PyVer[".python-version"]:::doc
    end

    User -->|"HTTPS/WebSocket"| Chainlit
    Chainlit -->|"calls Agent"| Agent
    Agent -->|"validate"| Guardrails
    Agent -->|"invoke Tool"| Tools
    Agent -->|"HTTP request"| LLM
    LLM -->|"response"| Agent
    Agent -->|"returns response"| Chainlit
    Chainlit -->|"log write"| DB
    Chainlit -->|"read/write"| DB_shm
    Chainlit -->|"read/write"| DB_wal
    Config -->|"load at startup"| Chainlit
    Config -->|"load at startup"| Agent
    Docs --> Chainlit
    PyProj --> Chainlit
    UvLock --> Chainlit
    PyVer --> Chainlit

    click CL_main "https://github.com/muhammadhassaanarain/dictionary-agent/blob/main/main.py"
    click CL_conf "https://github.com/muhammadhassaanarain/dictionary-agent/blob/main/.chainlit/config.toml"
    click Translations "https://github.com/muhammadhassaanarain/dictionary-agent/tree/main/.chainlit/translations/"
    click Agent "https://github.com/muhammadhassaanarain/dictionary-agent/blob/main/agent.py"
    click Guardrails "https://github.com/muhammadhassaanarain/dictionary-agent/blob/main/guardrails.py"
    click Tools "https://github.com/muhammadhassaanarain/dictionary-agent/blob/main/tools/tools.py"
    click Config "https://github.com/muhammadhassaanarain/dictionary-agent/blob/main/configuration.py"
    click DB "https://github.com/muhammadhassaanarain/dictionary-agent/blob/main/conversation.db"
    click DB_shm "https://github.com/muhammadhassaanarain/dictionary-agent/blob/main/conversation.db-shm"
    click DB_wal "https://github.com/muhammadhassaanarain/dictionary-agent/blob/main/conversation.db-wal"
    click Docs "https://github.com/muhammadhassaanarain/dictionary-agent/blob/main/chainlit.md"
    click PyProj "https://github.com/muhammadhassaanarain/dictionary-agent/blob/main/pyproject.toml"
    click UvLock "https://github.com/muhammadhassaanarain/dictionary-agent/blob/main/uv.lock"
    click PyVer "https://github.com/muhammadhassaanarain/dictionary-agent/blob/main/.python-version"

    classDef primary fill:#CFE2FF,stroke:#2858A3,color:#000
    classDef db fill:#D9EAD3,stroke:#6AA84F,color:#000
    classDef cloud fill:#FFE599,stroke:#B07C22,color:#000
    classDef doc fill:#F4CCCC,stroke:#CC0000,color:#000
```
