# dexhorthy/mailcrew architecture

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

- Interactive diagram: https://gitdiagram.com/dexhorthy/mailcrew
- Repository: https://github.com/dexhorthy/mailcrew

## Overview

##### Main Components

a) External Services Layer:
- Email Interface (Humanlayer)
- Stripe API
- Coinbase API
- User Email Client

b) Application Core:
- FastAPI Server
- CrewAI Agent System
- Webhook Handler
- Task Processing Pipeline

**[External Services/Interfaces]**
- ↕
**[Application Core Components]**
- ↕
**[External APIs/Integrations]**

##### Key Flows

a) Primary Flow:
- User → Email → Humanlayer → Webhook → FastAPI Server → Agent Processing → Response Chain

b) Secondary Flows:
- Agent → Stripe/Coinbase API Interactions
- Approval/Feedback Loop with Users

##### Detailed Component Breakdown

FastAPI Server:
- Webhook endpoint (/api/v1/webhook/email)
- Agent initialization
- Request processing

Agent System:
- Task interpretation
- API interaction planning
- Response generation
- Approval workflow management

##### Important Relationships

- Bidirectional communication between Agent and User via email
- One-way authentication flows to external APIs
- Webhook routing path
- Approval/confirmation loops

##### Additional Elements

- Component types
- Authentication points

##### Implementation Notes

- Clear component separation
- Logical flow direction (typically top to bottom or left to right)
- Proper spacing for readability
- Consistent styling throughout

Remember to include environment configuration points and the security boundary between public-facing components and protected API interactions.

This level of detail will provide a clear understanding of the system while maintaining practical usability for development and deployment discussions.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef external fill:#a8d1f0,stroke:#333
    classDef core fill:#90EE90,stroke:#333
    classDef processing fill:#FFE5B4,stroke:#333
    classDef security fill:#FFB6C6,stroke:#333
    classDef documentation fill:#E6E6FA,stroke:#333

    %% External Services Layer
    subgraph ExternalServices
        Email["Email Interface (Humanlayer)"]:::external
        FinServices["Financial Services"]:::external
        LangModel["Language Model Service"]:::external
        
        subgraph EmailSystem
            EmailEndpoint["Email Endpoints"]:::external
            WebhookHandler["Webhook Handler"]:::external
            EmailParser["Email Parser"]:::external
        end
        
        subgraph FinancialAPIs
            StripeAPI["Stripe API"]:::external
            CoinbaseAPI["Coinbase API"]:::external
        end
    end

    %% Core Application Layer
    subgraph CoreApplication
        FastAPI["FastAPI Server"]:::core
        WebhookController["/api/v1/webhook/email"]:::core
        AgentSystem["Agent System"]:::core
        ConfigMgmt["Configuration Management"]:::core
        
        subgraph APIComponents
            RequestValidator["Request Validator"]:::core
            ResponseHandler["Response Handler"]:::core
            ErrorHandler["Error Handler"]:::core
        end
    end

    %% Agent Processing Layer
    subgraph AgentProcessing
        CrewAI["CrewAI Agent"]:::processing
        TaskParser["Task Parser/Analyzer"]:::processing
        ResponseGen["Response Generator"]:::processing
        ToolCallSystem["Tool Call Draft System"]:::processing
        ApprovalManager["Approval Flow Manager"]:::processing
        
        subgraph TaskManagement
            Queue["Task Queue"]:::processing
            StateManager["State Manager"]:::processing
            ContextKeeper["Context Preservation"]:::processing
        end
    end

    %% Security Layer
    subgraph SecurityLayer
        Auth["Authentication System"]:::security
        APIKeys["API Key Management"]:::security
        EmailValidator["Email Validation"]:::security
        EnvConfig["Environment Config"]:::security
    end

    %% Monitoring Layer
    subgraph MonitoringSystem
        RequestLogger["Request Logging"]:::core
        ErrorTracker["Error Tracking"]:::core
        PerfMonitor["Performance Monitor"]:::core
        APITracker["API Call Tracker"]:::core
        EmailStatus["Email Delivery Status"]:::core
    end

    %% Relationships
    Email --> EmailSystem
    EmailSystem --> WebhookController
    WebhookController --> RequestValidator
    RequestValidator --> AgentSystem
    AgentSystem --> CrewAI
    CrewAI --> TaskParser
    TaskParser --> ToolCallSystem
    ToolCallSystem --> ApprovalManager
    ApprovalManager --> FinancialAPIs
    FinancialAPIs --> ResponseHandler
    ResponseHandler --> EmailSystem

    %% Security Connections
    Auth -.-> WebhookController
    APIKeys -.-> FinancialAPIs
    EmailValidator -.-> EmailSystem
    EnvConfig -.-> CoreApplication

    %% Monitoring Connections
    RequestLogger --> MonitoringSystem
    ErrorTracker --> MonitoringSystem
    PerfMonitor --> MonitoringSystem
    APITracker --> MonitoringSystem
    EmailStatus --> MonitoringSystem

    %% Click Events
    click FastAPI "https://github.com/dexhorthy/mailcrew/blob/main/api/app/main.py"
    click AgentSystem "https://github.com/dexhorthy/mailcrew/blob/main/api/app/agent.py"
    click EnvConfig "https://github.com/dexhorthy/mailcrew/blob/main/api/dotenv.example"
    click APIComponents "https://github.com/dexhorthy/mailcrew/blob/main/api/api.knowledge.md"
    click CoreApplication "https://github.com/dexhorthy/mailcrew/blob/main/api/pyproject.toml"
    click MonitoringSystem "https://github.com/dexhorthy/mailcrew/tree/main/api/Makefile"
    click TaskManagement "https://github.com/dexhorthy/mailcrew/tree/main/doc/"
    click SecurityLayer "https://github.com/dexhorthy/mailcrew/tree/main/doc/images/"

    %% Legend
    subgraph Legend
        ExtService["External Service"]:::external
        CoreComp["Core Component"]:::core
        ProcComp["Processing Component"]:::processing
        SecComp["Security Component"]:::security
        DocComp["Documentation"]:::documentation
    end
```
