# tsanford01/ai-soc-investigator architecture

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

- Interactive diagram: https://gitdiagram.com/tsanford01/ai-soc-investigator
- Repository: https://github.com/tsanford01/ai-soc-investigator

## Overview

##### Main Components

A. Agent Layer (Core Components):
- AI Agent (OpenAI Integration)
- Decision Agent
- Case Selection Agent
- Investigation Agent
- Notification Agent (Slack Integration)
- Coordinator Agent (Central Orchestrator)

B. Infrastructure Layer:
- Database (Supabase)
- Cases Table
- Decision Metrics Table
- External Services
- OpenAI API
- Slack API

C. Supporting Components:
- API Client Layer
- Authentication Service
- Rate Limiter
- Retry Mechanism

##### Component Relationships

- Coordinator Agent → All Other Agents (orchestration flow)
- All Agents ←→ Supabase Client (data access)
- AI Agent ←→ OpenAI API
- Notification Agent ←→ Slack API
- All Components ←→ Authentication Service

##### Specific Implementation Details

A. Top Level:
**[External Systems] → [API Layer] → [Agent Orchestration] → [Database Layer]**

B. Agent Workflow:
**Case Selection → Investigation → Decision → Notification**

C. Cross-Cutting Concerns:
- Error handling paths
- Retry mechanisms
- Rate limiting boundaries

##### Additional Elements

- Environment Configuration
- Error Handling Framework
- Performance Optimization Layer
- Monitoring & Logging

##### Architectural Patterns to Highlight

- Multi-agent architecture
- Service-oriented design
- Event-driven communication
- Repository pattern for data access
- Strategy pattern for agent behaviors

##### Technical Details

- Python as primary language
- Supabase for persistence
- OpenAI GPT for analysis
- Async patterns for performance
- Transaction boundaries

##### Security Boundaries

Indicate:
- Authentication boundaries
- API security layers
- Data encryption points

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef agent fill:#3498db,stroke:#2980b9,color:white
    classDef infrastructure fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef external fill:#2ecc71,stroke:#27ae60,color:white
    classDef support fill:#e67e22,stroke:#d35400,color:white
    classDef database fill:#9b59b6,stroke:#8e44ad,color:white
    classDef config fill:#34495e,stroke:#2c3e50,color:white

    %% Infrastructure Layer
    subgraph Infrastructure
        DB[(Supabase DB)]:::database
        DBCases[("Cases Table")]:::database
        DBMetrics[("Decision Metrics")]:::database
        DB --> DBCases
        DB --> DBMetrics
    end

    %% External Services
    subgraph External
        OpenAI["OpenAI API"]:::external
        Slack["Slack API"]:::external
    end

    %% Supporting Services
    subgraph Support
        Auth["Authentication Service"]:::support
        RateLimit["Rate Limiter"]:::support
        Retry["Retry Mechanism"]:::support
        APIClient["API Client Layer"]:::support
    end

    %% Configuration
    Config["Environment Config"]:::config

    %% Core Agent Layer
    subgraph Agents
        Coordinator["Coordinator Agent"]:::agent
        AIAgent["AI Agent"]:::agent
        DecisionAgent["Decision Agent"]:::agent
        CaseAgent["Case Selection Agent"]:::agent
        InvestAgent["Investigation Agent"]:::agent
        NotifyAgent["Notification Agent"]:::agent
        Registry["Agent Registry"]:::agent
        BaseAgent["Base Agent Framework"]:::agent
    end

    %% Case Processing
    CaseProcessor["Case Processing"]:::support
    DataProcessor["Data Processor"]:::support

    %% Relationships
    Coordinator --> AIAgent
    Coordinator --> DecisionAgent
    Coordinator --> CaseAgent
    Coordinator --> InvestAgent
    Coordinator --> NotifyAgent
    
    AIAgent --> OpenAI
    NotifyAgent --> Slack
    
    Agents --> APIClient
    APIClient --> DB
    
    All --> Auth
    All --> RateLimit
    All --> Retry
    
    CaseProcessor --> Agents
    DataProcessor --> CaseProcessor

    %% Click Events
    click AIAgent "https://github.com/tsanford01/ai-soc-investigator/blob/main/src/agents/ai_agent.py"
    click DecisionAgent "https://github.com/tsanford01/ai-soc-investigator/blob/main/src/agents/decision_agent.py"
    click NotifyAgent "https://github.com/tsanford01/ai-soc-investigator/blob/main/notification_agent.py"
    click Coordinator "https://github.com/tsanford01/ai-soc-investigator/blob/main/src/agents/supervisor/agent_supervisor.py"
    click DB "https://github.com/tsanford01/ai-soc-investigator/blob/main/src/clients/supabase_client.py"
    click APIClient "https://github.com/tsanford01/ai-soc-investigator/blob/main/src/clients/api_client.py"
    click Auth "https://github.com/tsanford01/ai-soc-investigator/blob/main/src/clients/auth.py"
    click RateLimit "https://github.com/tsanford01/ai-soc-investigator/blob/main/src/utils/rate_limiter.py"
    click Retry "https://github.com/tsanford01/ai-soc-investigator/blob/main/src/utils/retry.py"
    click Registry "https://github.com/tsanford01/ai-soc-investigator/blob/main/src/agents/registry/agent_registry.py"
    click BaseAgent "https://github.com/tsanford01/ai-soc-investigator/blob/main/src/agents/base/base_agent.py"
    click Config "https://github.com/tsanford01/ai-soc-investigator/blob/main/src/config/settings.py"
    click CaseProcessor "https://github.com/tsanford01/ai-soc-investigator/blob/main/src/agents/specialized/case_handler.py"
    click DataProcessor "https://github.com/tsanford01/ai-soc-investigator/blob/main/src/agents/specialized/data_processor.py"
```
