# trafficguard/sophia architecture

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

- Interactive diagram: https://gitdiagram.com/trafficguard/sophia
- Repository: https://github.com/trafficguard/sophia

## Overview

##### High-Level Architecture Components

a) Core Platform Components:
- Agent System
- LLM Integration Layer
- Function Registry
- Authentication/Authorization
- Web UI (Angular-based)
- CLI Interface
- Storage Layer

b) External Integrations:
- LLM Providers (OpenAI, Anthropic, etc.)
- Development Tools (Git, GitLab, GitHub)
- Cloud Services (Google Cloud)
- Communication Tools (Slack)
- Project Management (Jira)

##### Detailed Component Breakdown

a) Agent System:
- Agent Runner
- Agent Context
- Workflow Engine
- Human-in-the-Loop Interface
- Memory Management
- Function Cache

b) LLM Layer:
- LLM Factory
- Multi-Agent Implementation
- Response Parsers
- Token Management
- Service Adapters

c) Function System:
- Function Registry
- Schema Parser
- Function Decorators
- Tool Types

##### Data Flow Representation

Following flows:
- Agent execution pipeline
- Authentication flow
- Function calling sequence
- Human interaction points
- Storage operations

##### Component Relationships

Key relationships:
- Agent → LLM Services
- Agent → Function Registry
- Web UI → Backend Services
- CLI → Backend Services
- Authentication → All Protected Services

##### Deployment View

A separate section showing:
- Local deployment option
- Cloud deployment (Google Cloud Run + Firestore)
- Scale-to-zero configuration
- Multi-user SSO setup

##### Observability Layer

Highlight:
- OpenTelemetry integration
- Logging system
- Trace collection
- Monitoring points

##### Security Boundaries

Indicate:
- Authentication boundaries
- Function execution sandbox
- API security layers
- SSO integration points

Key aspects to emphasize:
- The autonomous agent architecture
- The flexible LLM integration system
- The function calling infrastructure
- The human-in-the-loop integration points
- The observability system
- The deployment options

This system design should effectively communicate both the high-level architecture and the detailed component interactions while highlighting the platform's key features and flexibility.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Core["Core Platform"]
        direction TB
        AgentSys["Agent System"]:::core
        LLMInt["LLM Integration Layer"]:::core
        FuncReg["Function Registry"]:::core
        Auth["Authentication/Authorization"]:::core
        WebUI["Web UI (Angular)"]:::ui
        CLI["CLI Interface"]:::ui
        Storage["Storage Layer"]:::storage
    end

    subgraph External["External Integrations"]
        direction TB
        LLMProv["LLM Providers"]:::external
        DevTools["Development Tools"]:::external
        Cloud["Cloud Services"]:::external
        Comms["Communication Tools"]:::external
        ProjMgmt["Project Management"]:::external
    end

    subgraph AgentComponents["Agent System Components"]
        direction TB
        Runner["Agent Runner"]:::agent
        Context["Agent Context"]:::agent
        Workflow["Workflow Engine"]:::agent
        HITL["Human-in-the-Loop"]:::agent
        Memory["Memory Management"]:::agent
        Cache["Function Cache"]:::agent
    end

    subgraph LLMLayer["LLM Layer"]
        direction TB
        Factory["LLM Factory"]:::llm
        MultiAgent["Multi-Agent Implementation"]:::llm
        Parser["Response Parsers"]:::llm
        TokenMgmt["Token Management"]:::llm
        Adapters["Service Adapters"]:::llm
    end

    subgraph Observability["Observability"]
        direction TB
        OpenTel["OpenTelemetry"]:::obs
        Logging["Logging System"]:::obs
        Tracing["Trace Collection"]:::obs
        Monitor["Monitoring"]:::obs
    end

    %% Core Relationships
    AgentSys --> LLMInt
    AgentSys --> FuncReg
    WebUI --> Auth
    CLI --> Auth
    Auth --> AgentSys
    AgentSys --> Storage

    %% External Integration Relationships
    LLMInt --> LLMProv
    FuncReg --> DevTools
    FuncReg --> Cloud
    FuncReg --> Comms
    FuncReg --> ProjMgmt

    %% Agent Component Relationships
    AgentSys --> Runner
    Runner --> Context
    Context --> Workflow
    Workflow --> HITL
    Context --> Memory
    Runner --> Cache

    %% LLM Layer Relationships
    LLMInt --> Factory
    Factory --> MultiAgent
    Factory --> Parser
    Factory --> TokenMgmt
    Factory --> Adapters

    %% Observability Relationships
    AgentSys --> OpenTel
    LLMInt --> OpenTel
    FuncReg --> OpenTel
    OpenTel --> Logging
    OpenTel --> Tracing
    OpenTel --> Monitor

    %% Click Events
    click AgentSys "https://github.com/TrafficGuard/sophia/tree/main/src/agent/"
    click LLMInt "https://github.com/TrafficGuard/sophia/tree/main/src/llm/"
    click FuncReg "https://github.com/TrafficGuard/sophia/blob/main/src/functionRegistry.ts"
    click Auth "https://github.com/TrafficGuard/sophia/blob/main/src/fastify/authenticationMiddleware.ts"
    click WebUI "https://github.com/TrafficGuard/sophia/tree/main/frontend/src/app/"
    click CLI "https://github.com/TrafficGuard/sophia/tree/main/src/cli/"
    click Storage "https://github.com/TrafficGuard/sophia/tree/main/src/functions/storage/"
    click LLMProv "https://github.com/TrafficGuard/sophia/tree/main/src/llm/services/"
    click DevTools "https://github.com/TrafficGuard/sophia/tree/main/src/functions/scm/"
    click Cloud "https://github.com/TrafficGuard/sophia/tree/main/src/functions/cloud/"
    click Comms "https://github.com/TrafficGuard/sophia/tree/main/src/modules/slack/"
    click ProjMgmt "https://github.com/TrafficGuard/sophia/blob/main/src/functions/jira.ts"
    click OpenTel "https://github.com/TrafficGuard/sophia/tree/main/src/o11y/"
    click HITL "https://github.com/TrafficGuard/sophia/blob/main/src/agent/humanInTheLoop.ts"
    click Cache "https://github.com/TrafficGuard/sophia/blob/main/src/cache/functionCacheService.ts"
    click Memory "https://github.com/TrafficGuard/sophia/tree/main/src/modules/memory/"

    %% Styling
    classDef core fill:#2374ab
    classDef external fill:#57a773
    classDef ui fill:#7d7abc
    classDef storage fill:#484848
    classDef agent fill:#9c528b
    classDef llm fill:#1ea896
    classDef obs fill:#f1a66a

    %% Legend
    subgraph Legend
        direction TB
        L1["Core Components"]:::core
        L2["External Integrations"]:::external
        L3["UI Components"]:::ui
        L4["Storage"]:::storage
        L5["Agent Components"]:::agent
        L6["LLM Components"]:::llm
        L7["Observability"]:::obs
    end
```
