# joshuac215/agent-service-toolkit architecture

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

- Interactive diagram: https://gitdiagram.com/joshuac215/agent-service-toolkit
- Repository: https://github.com/joshuac215/agent-service-toolkit

## Overview

##### Project Overview & Type
- The project is a full-stack application that provides a robust AI agent service. It leverages LangGraph for agent logic, FastAPI for serving API endpoints, and Streamlit for a user-friendly interface.
- It is designed both for local development and containerized deployment (using Docker), with components for agent management, client interactions, and testing.

##### Analyzing the File Structure
- The top-level directories include:
- src/: Contains all production code.
▸ agents/: Implements various AI agents (e.g., chatbot, research assistant, background task agent) and tools.
▸ client/: Houses the client logic to interact with the agent service.
▸ core/: Holds critical modules such as the LLM configurations and app settings.
▸ memory/: Implements storage mechanisms (SQLite and Postgres) for maintaining state or contextual data.
▸ service/: Contains the FastAPI-based service used to expose agent endpoints.
▸ schema/: Defines data models and Pydantic schemas which support API payloads and validation.
- tests/: Provides unit and integration tests for different components ensuring quality (agents, client, service, core functionalities).
- Auxiliary files like Dockerfiles, Docker Compose configuration, and pre-commit hooks highlight containerization and development best practices.

a. Main Components:
- API Service Layer: Represented by src/service/service.py, which runs the FastAPI application.
- AI Agents: Located in src/agents/; include specific agents like chatbot, research assistant, etc. This group is responsible for processing and handling requests.
- Client Module: In src/client/client.py, this component interfaces with the FastAPI service.
- Core & Configuration: In src/core (LLM settings, configurations) and src/schema (data model definitions) that provide common utilities and enforce standards.
- Memory Storage: Components in src/memory (SQLite, Postgres) that store session data or agent state.
- UI Interface: In src/streamlit_app.py, showcasing the chat interface for end-users.
- Docker & Deployment: Dockerfiles and compose.yaml represent the containerized environments for running both the Agent Service and Streamlit app.

b. Relationships & Interactions:
- A client (from src/client or external applications) sends requests to the FastAPI service.
- The service (FastAPI) routes these to the appropriate agent (selected from src/agents) based on the URL path and endpoint.
- The agents then use utilities from core and schema for validation and processing.
- Memory mechanisms (SQLite/Postgres) may be involved for storing state or historical data.
- The Streamlit UI communicates with the service (using the client library) to present a chat interface.
- Docker components encapsulate the environment, ensuring that the service, UI, and client can be independently deployed and scaled.

c. Architectural Patterns & Design Principles:
- Layered/MVC-like Structure: Separation into distinct modules (UI, API, business logic, data storage) clearly organized in different directories.
- Microservices-like Separation: Although within one repository, the agents, service, and UI can be conceived as independent components that interoperate.
- Asynchronous Design: The codebase makes extensive use of async/await (especially in handling concurrent requests through FastAPI).
- Containerization: Usage of Dockerfiles and Docker Compose emphasizes a portable and reproducible deployment environment.

d. Relevant Technologies & Frameworks:
- LangGraph (for agent orchestration)
- FastAPI (for the service)
- Streamlit (for the UI)
- Pydantic (for data models and settings)
- Docker & Docker Compose (for containerizing the environment)
- Testing frameworks (pytest for unit and integration tests)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend & Client Layer
    subgraph "Frontend & Client Layer"
        CM["Client Module"]:::client
        UI["Streamlit UI"]:::ui
    end

    %% Backend Service Layer
    subgraph "Backend Service Layer"
        API["FastAPI Service"]:::api
    end

    %% Business Logic & Agents
    subgraph "Business Logic & Agents"
        AG["LangGraph Agents"]:::agent
    end

    %% Core & Configuration
    subgraph "Core & Configuration"
        LLM["LLM"]:::core
        SET["Settings"]:::core
        SM["Schema Models"]:::core
    end

    %% Memory Storage
    subgraph "Memory Storage"
        SQLITE["SQLite Storage"]:::memory
        POSTGRES["Postgres Storage"]:::memory
    end

    %% Deployment Layer
    subgraph "Deployment Layer"
        DAPP["Docker: App"]:::docker
        DSERV["Docker: Service"]:::docker
        DCMP["Docker Compose"]:::docker
    end

    %% Connections
    CM -->|"sends_request"| API
    UI -->|"user_interface"| API
    API -->|"routes_to"| AG
    AG -->|"uses"| LLM
    AG -->|"uses"| SET
    AG -->|"validates_with"| SM
    AG -->|"stores_via"| SQLITE
    AG -->|"stores_via"| POSTGRES
    DAPP --> DCMP
    DSERV --> DCMP
    DCMP -->|"deploys"| API
    DCMP -->|"deploys"| UI

    %% Click Events
    click API "https://github.com/joshuac215/agent-service-toolkit/blob/main/src/service/service.py"
    click AG "https://github.com/joshuac215/agent-service-toolkit/tree/main/src/agents/"
    click CM "https://github.com/joshuac215/agent-service-toolkit/blob/main/src/client/client.py"
    click LLM "https://github.com/joshuac215/agent-service-toolkit/blob/main/src/core/llm.py"
    click SET "https://github.com/joshuac215/agent-service-toolkit/blob/main/src/core/settings.py"
    click SM "https://github.com/joshuac215/agent-service-toolkit/blob/main/src/schema/models.py"
    click SQLITE "https://github.com/joshuac215/agent-service-toolkit/blob/main/src/memory/sqlite.py"
    click POSTGRES "https://github.com/joshuac215/agent-service-toolkit/blob/main/src/memory/postgres.py"
    click UI "https://github.com/joshuac215/agent-service-toolkit/blob/main/src/streamlit_app.py"
    click DAPP "https://github.com/joshuac215/agent-service-toolkit/blob/main/docker/Dockerfile.app"
    click DSERV "https://github.com/joshuac215/agent-service-toolkit/blob/main/docker/Dockerfile.service"
    click DCMP "https://github.com/joshuac215/agent-service-toolkit/blob/main/compose.yaml"

    %% Styles
    classDef api fill:#ffadad,stroke:#333,stroke-width:2px;
    classDef agent fill:#ffd6a5,stroke:#333,stroke-width:2px;
    classDef client fill:#fdffb6,stroke:#333,stroke-width:2px;
    classDef core fill:#caffbf,stroke:#333,stroke-width:2px;
    classDef memory fill:#9bf6ff,stroke:#333,stroke-width:2px;
    classDef ui fill:#a0c4ff,stroke:#333,stroke-width:2px;
    classDef docker fill:#bdb2ff,stroke:#333,stroke-width:2px;
```
