# p-breslin/zero-touch architecture

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

- Interactive diagram: https://gitdiagram.com/p-breslin/zero-touch
- Repository: https://github.com/p-breslin/zero-touch

## Overview

##### Project type and purpose
- This is a data-processing orchestration engine (not a typical web app). It uses the Agno Agent Framework to build a pipeline of AI “agents” that extract, plan, generate, and execute SQL against engineering data (GitHub/JIRA) and resolve identities.
- Its goal is to infer organizational structure automatically and (eventually) populate an Object-Oriented Graph in ArangoDB.

##### File structure
- Top-level “configs/” holds YAML configs for agents, prompts, and query templates.
- “services/” encapsulates DB connectivity, engine creation, and data export logic (Snowflake → CSV).
- “scripts/” contains setup scripts to provision DuckDB, ChromaDB, and ArangoDB.
- “models/” defines Pydantic schemas (SQLPlan, AggregatedData, IdentityList, etc.).
- “src/” houses the core logic:
- orchestrator.py (pipeline driver)
- agents/ (builder, base class)
- paths.py, test.py
- “dev/” and “utils/” contain helper scripts and logging setup.

##### Extracted insights from README
- Four main layers: Data Sources, Knowledge Base (ChromaDB), Agno Agent Framework, and (future) Graph DB (ArangoDB).
- Pipeline steps:
1. Orchestrator kicks off
2. KnowledgeBase Agent retrieves schema info via ChromaDB
3. Planner Agent creates an SQLPlan
4. SQL Constructor Agent builds SQL strings
5. SQL Executor Agents run queries in parallel on DuckDB
6. Orchestrator aggregates results
7. Identity Agent resolves unique persons
8. (Future) Graph Agent will load results into ArangoDB

a. Main components
- External Data Sources: GitHub, JIRA (Snowflake)
- Setup Scripts: SnowflakeDownload → DuckDBSetup → ChromaDBSetup → ArangoDBSetup
- Databases:
- DuckDB (local mirror)
- ChromaDB (vector store for schema KB)
- ArangoDB (OOG graph)
- Service Layer: connection_manager, create_engine, snowflake_download
- Agent Framework Layer:
- Orchestrator
- Agents (KnowledgeBase, Planner, SQLConstructor, SQLExecutor, Identity)
- Models: Pydantic schemas for data contracts
- Configs & Utils: YAML configs, helpers, logging

b. Relationships & interactions
- Data flow: GitHub/JIRA → SnowflakeDownload service → CSV files → DuckDB
- ChromaDBSetup loads schema JSON → ChromaDB
- Orchestrator reads configs → instantiates Agents
- KnowledgeBase Agent queries ChromaDB → returns schema info
- Planner Agent consumes schema info → outputs SQLPlan
- SQLConstructor Agent transforms SQLPlan → SQL strings
- SQLExecutor Agents execute SQL on DuckDB → return raw rows
- Orchestrator aggregates rows → AggregatedData
- Identity Agent resolves persons → IdentityList
- (Future) Graph Agent writes entities/relations to ArangoDB

c. Architectural patterns & principles
- Extreme Task Decomposition: very fine-grained agents each with a single responsibility
- Centralized orchestration: orchestrator directs sequence, parallelism, error checks
- Clear data contracts via Pydantic models
- Configuration-driven: YAML files decouple code from prompts and settings

d. Key technologies
- Python 3.12+, Agno Agent Framework, OpenAI/LLMs
- SQLAlchemy (DuckDB, Snowflake)
- ChromaDB (vector knowledge base)
- DuckDB (local dev mirror)
- ArangoDB (graph store)
- Pydantic models, python-dotenv, uv for builds

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources
    GH["GitHub"]:::external
    JIRA["JIRA (Snowflake)"]:::external

    %% Services & Setup Scripts
    SD["Snowflake Download Service"]:::service
    CM["Connection Manager"]:::service
    CE["Engine Creation Service"]:::service
    DS["DuckDB Setup Script"]:::service
    CS["ChromaDB Setup Script"]:::service
    KS["ArangoDB (KG) Setup Script"]:::service

    %% Databases
    DDB["DuckDB"]:::db
    CDB["ChromaDB"]:::db
    ADB["ArangoDB"]:::db

    %% Configs & Models
    subgraph "Configs"
        AGCFG["Agent Configs"]:::config
        INCFG["Instruction Prompts"]:::config
        SQLCFG["SQL Templates"]:::config
    end
    subgraph "Models"
        KBM["KnowledgeBase Models"]:::model
        PLM["Planner Models"]:::model
        SCM["SQLConstructor Models"]:::model
        AGM["Aggregator Models"]:::model
        IGM["Identity Models"]:::model
    end

    %% Agent Framework
    subgraph "Agent Framework"
        ORC["Orchestrator"]:::agent
        AB["Agent Builder"]:::agent
        BA["Base Agent"]:::agent
        KBAG["KnowledgeBase Agent"]:::agent
        PLAN["Planner Agent"]:::agent
        SQLC["SQLConstructor Agent"]:::agent
        SQLX["SQLExecutor Agents"]:::agent
        IDAG["Identity Agent"]:::agent
        FGAG["Future Graph Agent"]:::agent
    end

    %% Utils & Others
    PD["Path Definitions"]:::aux
    TEST["Test Harness"]:::aux
    DEVQ["Dev SQL Queries"]:::aux
    HELP["Utility Helpers"]:::aux
    LOG["Logging Setup"]:::aux

    %% Connections
    GH --> SD
    JIRA --> SD
    SD --> DS
    DS --> DDB
    CS --> CDB
    KS --> ADB

    CM -.-> CE
    CE -.-> DS

    ORC --> AGCFG
    ORC --> INCFG
    ORC --> SQLCFG
    ORC --> PD
    ORC --> AB
    ORC --> BA

    ORC --> KBAG
    KBAG --> CDB
    CDB --> KBAG
    KBAG --> PLM
    PLM --> PLAN
    PLAN --> SCM
    SCM --> SQLC
    SQLC --> SQLX
    SQLX --> DDB
    DDB --> SQLX
    SQLX --> ORC

    ORC --> AGM
    AGM --> IGM
    ORC --> IDAG
    IDAG --> ORC

    ORC --> FGAG
    FGAG --> ADB

    ORC --> TEST
    ORC --> HELP
    ORC --> LOG
    DEVQ -.-> ORC

    %% Click Events
    click ORC "https://github.com/p-breslin/zero-touch/blob/main/src/orchestrator.py"
    click AB "https://github.com/p-breslin/zero-touch/blob/main/src/agents/agent_builder.py"
    click BA "https://github.com/p-breslin/zero-touch/blob/main/src/agents/base_agent.py"
    click KBM "https://github.com/p-breslin/zero-touch/blob/main/models/knowledgebase_models.py"
    click PLM "https://github.com/p-breslin/zero-touch/blob/main/models/planner_models.py"
    click SCM "https://github.com/p-breslin/zero-touch/blob/main/models/sql_constructor_models.py"
    click AGM "https://github.com/p-breslin/zero-touch/blob/main/models/aggregator_models.py"
    click IGM "https://github.com/p-breslin/zero-touch/blob/main/models/identity_models.py"
    click SD "https://github.com/p-breslin/zero-touch/blob/main/services/snowflake_download.py"
    click CM "https://github.com/p-breslin/zero-touch/blob/main/services/connection_manager.py"
    click CE "https://github.com/p-breslin/zero-touch/blob/main/services/create_engine.py"
    click DS "https://github.com/p-breslin/zero-touch/blob/main/scripts/duckdb_setup.py"
    click CS "https://github.com/p-breslin/zero-touch/blob/main/scripts/chromadb_setup.py"
    click KS "https://github.com/p-breslin/zero-touch/blob/main/scripts/KG_setup.py"
    click AGCFG "https://github.com/p-breslin/zero-touch/blob/main/configs/agents.yaml"
    click INCFG "https://github.com/p-breslin/zero-touch/blob/main/configs/instructions.yaml"
    click SQLCFG "https://github.com/p-breslin/zero-touch/blob/main/configs/queries.yaml"
    click PD "https://github.com/p-breslin/zero-touch/blob/main/src/paths.py"
    click DEVQ "https://github.com/p-breslin/zero-touch/blob/main/dev/sql_queries.py"
    click HELP "https://github.com/p-breslin/zero-touch/blob/main/utils/helpers.py"
    click LOG "https://github.com/p-breslin/zero-touch/blob/main/utils/logging_setup.py"
    click TEST "https://github.com/p-breslin/zero-touch/blob/main/src/test.py"

    %% Styles
    classDef external fill:#BBDEFB,stroke:#0277BD
    classDef service fill:#C8E6C9,stroke:#2E7D32
    classDef db fill:#90CAF9,stroke:#1565C0,shape:cylinder
    classDef config fill:#E1BEE7,stroke:#6A1B9A
    classDef model fill:#CE93D8,stroke:#8E24AA
    classDef agent fill:#FFCC80,stroke:#EF6C00
    classDef aux fill:#F5F5F5,stroke:#9E9E9E
```
