# josh-xt/agixt architecture

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

- Interactive diagram: https://gitdiagram.com/josh-xt/agixt
- Repository: https://github.com/josh-xt/agixt

## Overview

##### Project type and purpose
- AGiXT is a modular “AI Automation Platform” implemented in Python. It provides a FastAPI‐based RESTful API for orchestrating AI instruction management, task execution, conversation chains, memory handling, and a plugin/extension system.
- It integrates multiple AI back ends (OpenAI, Hugging Face, local ONNX models, etc.), manages agents, prompts, chains, and supports third-party authentication via SSO.

##### File structure
- Top level
- start.py, Dockerfile, docker-compose.yml: initialization and deployment scripts
- pyproject.toml, requirements.txt, setup.py: packaging and dependencies
- agixt/ (core package)
- app.py: FastAPI app entrypoint
- endpoints/: HTTP route handlers (Agent, Chain, Completions, Conversation, Memory, Prompt, Provider, Tasks, Health, GQL, etc.)
- Agent.py, Chain.py, Task.py, TaskMonitor.py, Conversations.py, Models.py, Prompts.py, Providers.py, Memories.py, DB.py, Interactions.py, MagicalAuth.py, SessionTracker.py, etc.: core orchestration modules
- extensions/: plugin modules (web browsing, cameras, databases, file system, scheduled tasks, etc.)
- providers/: adapters to various AI providers (OpenAI, Azure, HuggingFace, GPT4Free, local)
- sso/: OAuth2 handlers for GitHub, Google, Microsoft, Alexa, Tesla, etc.
- onnx/: local model artifacts and tokenizer configs
- prompts/, chains/, conversations/: JSON/YAML definitions of workflows
- Configuration & supporting directories
- docker-compose*.yml, .github/workflows, docs/, examples/, tests/

##### README insights

a. Main components
1. Client layer
– SDKs (Python, TypeScript, Dart, Rust, Zig)
– UIs (AGiXT Management UI, AGiXT Interactive UI)
2. API Gateway & Request ingress
– HTTP and WebSocket endpoints on Uvicorn/FastAPI (start.py → app.py)
3. Core backend modules
– Request router (endpoints/)
– Agent Manager (Agent.py, Workspaces.py, TaskMonitor.py)
– Chain Orchestrator (Chain.py, Chains definitions)
– Task Executor (Task.py)
– Memory Manager (Memories.py, vector/SQ store via DB.py)
– Prompt Manager (Prompts.py, prompt templates)
– Extension Executor (extensions/)
– Provider Adapter Layer (providers/) + ONNX runtime
– Authentication & SSO (MagicalAuth.py, sso/)
– Session Tracker & Logging (session_tracker.py, DB.py)
4. Data stores
– Relational DB (SQLite/Postgres) for metadata, logs
– Vector DB or embedding store (in-process or external)
5. External systems
– AI providers (OpenAI, Azure, Hugging Face, GPT4Free, local ONNX)
– Third-party services via extensions (web browsing, databases, cameras, scheduled tasks, etc.)
b. Relationships & data flows
- Clients → API Gateway → FastAPI endpoints
- Endpoints invoke core modules (Agent Manager → Chain Orchestrator or Prompt Inference or Task Executor)
- Core orchestrators read/write metadata to Relational DB, query/update vectors in Vector DB
- For inference: Provider Adapter → call external AI API or ONNX runtime
- Extension Executor → external services via plugin interfaces
- Results → format & return to client, with logging/tracing
- SSO flows: Client ←→ MagicalAuth / sso handlers
c. Architectural patterns & principles
- Modular monolith with plugin/extension architecture
- Adapter pattern for AI providers
- Workflow/chain orchestration pattern
- Clear separation of concerns: routing, orchestration, persistence, external integrations
- Dependency injection via FastAPI
d. Key technologies & frameworks
- Python 3.10+, FastAPI, Uvicorn
- SQLAlchemy or similar via DB.py for relational DB
- ONNX Runtime for local inference
- Docker & Docker Compose for deployment
- External AI APIs (OpenAI, Azure, Hugging Face, etc.)
- OAuth2 for SSO, REST for provider communication

##### Essential details
- Don’t over-modularize; group logically related modules under higher-level components
- SSO/authentication flow
- If using Docker Compose, show each service container (API service, ONNX service if separate, DB, vector store) and network links

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        SDK_Client["SDK Clients\n(Python, TS, Dart, Rust, Zig)"]:::frontend
        UI_Management["AGiXT Management UI"]:::frontend
        UI_Interactive["AGiXT Interactive UI"]:::frontend
    end

    %% API Gateway & Ingress
    subgraph "API Gateway & Ingress"
        direction TB
        StartScript["start.py\n(CLI & Docker Entrypoint)"]:::api
        FastAPIApp["agixt/app.py\n(Uvicorn/FastAPI)"]:::api
    end

    %% API Routing Layer
    subgraph "API Routing Layer"
        direction TB
        RequestRouter["agixt/endpoints/\n(HTTP & WebSocket Endpoints)"]:::api
    end

    %% Core Backend
    subgraph "Core Backend"
        direction TB
        AgentMgr["Agent Manager"]:::core
        ChainOrch["Chain Orchestrator"]:::core
        TaskExec["Task Executor"]:::core
        MemoryMgr["Memory Manager"]:::core
        PromptMgr["Prompt Manager"]:::core
        ExtExec["Extension Executor"]:::ext
        ProviderAdapter["Provider Adapter Layer"]:::core
        ONNXRuntime["Local ONNX Runtime"]:::core
        AuthSSO["Authentication & SSO"]:::core
        SessionTracker["Session Tracker & Logging"]:::core
        Conversations["Conversation Chains & Definitions"]:::core
        ModelsSchemas["Core Models & Schemas"]:::core
        Interactions["Interaction Utilities"]:::core
        Transcription["Transcription Support"]:::core
        Tuning["Model Tuning & Fine-tuning"]:::core
        Globals["Global Configuration & Constants"]:::core
        WorkspaceExample["Workspace Example & Seed Imports"]:::core
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        RelationalDB["Relational DB\n(SQLite/Postgres)"]:::store
        VectorDB["Vector DB / Embedding Store"]:::store
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        AI_Providers["AI Providers\n(OpenAI, Azure,\nHugging Face, GPT4Free)"]:::external
        ONNXModels["Local ONNX Models"]:::external
        ThirdParty["Third-Party Services\n(Web, DB, Cameras,\nScheduled Tasks)"]:::external
    end

    %% Connections
    SDK_Client -->|"API Requests"| StartScript
    UI_Management -->|"User Requests"| StartScript
    UI_Interactive -->|"User Requests"| StartScript

    StartScript -->|"loads"| FastAPIApp
    FastAPIApp -->|"routes to"| RequestRouter

    RequestRouter -->|"invoke"| AgentMgr
    RequestRouter -->|"invoke"| ChainOrch
    RequestRouter -->|"invoke"| TaskExec
    RequestRouter -->|"invoke"| MemoryMgr
    RequestRouter -->|"invoke"| PromptMgr
    RequestRouter -->|"invoke"| ExtExec
    RequestRouter -->|"invoke"| ProviderAdapter
    RequestRouter -->|"invoke"| AuthSSO
    RequestRouter -->|"invoke"| SessionTracker
    RequestRouter -->|"invoke"| Conversations

    AgentMgr -->|"reads/writes"| RelationalDB
    TaskExec -->|"reads/writes"| RelationalDB
    MemoryMgr -->|"reads/writes"| RelationalDB
    MemoryMgr -->|"queries/updates"| VectorDB
    SessionTracker -->|"logs to"| RelationalDB

    ChainOrch -->|"loads definitions"| Conversations
    ChainOrch -->|"executes"| TaskExec
    ChainOrch -->|"injects memory"| MemoryMgr
    ChainOrch -->|"formats prompt"| PromptMgr

    PromptMgr -->|"templates & context"| MemoryMgr
    PromptMgr -->|"sends to"| ProviderAdapter

    ProviderAdapter -->|"remote calls"| AI_Providers
    ProviderAdapter -->|"local inference"| ONNXRuntime

    ONNXRuntime -->|"uses models"| ONNXModels

    ExtExec -->|"plugin ops"| ThirdParty

    AuthSSO -->|"OAuth2 flows"| SDK_Client
    AuthSSO -->|"sessions"| SessionTracker

    %% Click Events
    click StartScript "https://github.com/josh-xt/agixt/blob/main/start.py"
    click FastAPIApp "https://github.com/josh-xt/agixt/blob/main/agixt/app.py"
    click RequestRouter "https://github.com/josh-xt/agixt/tree/main/agixt/endpoints/"
    click AgentMgr "https://github.com/josh-xt/agixt/blob/main/agixt/Agent.py"
    click ChainOrch "https://github.com/josh-xt/agixt/blob/main/agixt/Chain.py"
    click TaskExec "https://github.com/josh-xt/agixt/blob/main/agixt/Task.py"
    click MemoryMgr "https://github.com/josh-xt/agixt/blob/main/agixt/Memories.py"
    click PromptMgr "https://github.com/josh-xt/agixt/blob/main/agixt/Prompts.py"
    click ExtExec "https://github.com/josh-xt/agixt/blob/main/agixt/Extensions.py"
    click ProviderAdapter "https://github.com/josh-xt/agixt/blob/main/agixt/Providers.py"
    click ONNXRuntime "https://github.com/josh-xt/agixt/tree/main/agixt/onnx/"
    click AuthSSO "https://github.com/josh-xt/agixt/blob/main/agixt/MagicalAuth.py"
    click SessionTracker "https://github.com/josh-xt/agixt/blob/main/agixt/session_tracker.py"
    click Conversations "https://github.com/josh-xt/agixt/blob/main/agixt/Conversations.py"
    click ModelsSchemas "https://github.com/josh-xt/agixt/blob/main/agixt/Models.py"
    click Interactions "https://github.com/josh-xt/agixt/blob/main/agixt/Interactions.py"
    click Transcription "https://github.com/josh-xt/agixt/blob/main/agixt/Transcription.py"
    click Tuning "https://github.com/josh-xt/agixt/blob/main/agixt/Tuning.py"
    click Globals "https://github.com/josh-xt/agixt/blob/main/agixt/Globals.py"
    click WorkspaceExample "https://github.com/josh-xt/agixt/tree/main/agixt/WORKSPACE/"
    click SDK_Client "https://github.com/josh-xt/agixt/blob/main/agixt/ApiClient.py"

    %% Styles
    classDef frontend fill:#D6EFFF,stroke:#3F7FBF,stroke-width:1px;
    classDef api fill:#CCE5FF,stroke:#2F6F9F,stroke-width:1px;
    classDef core fill:#E6FFCC,stroke:#6F9F3F,stroke-width:1px;
    classDef store fill:#CCFFE5,stroke:#3F9F7F,stroke-width:1px;
    classDef ext fill:#F2CCFF,stroke:#9F3F9F,stroke-width:1px;
    classDef external fill:#FFD8CC,stroke:#9F5F2F,stroke-width:1px;
```
