# wolfsbane9513/influencer-ai architecture

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

- Interactive diagram: https://gitdiagram.com/wolfsbane9513/influencer-ai
- Repository: https://github.com/wolfsbane9513/influencer-ai

## Overview

##### Project Type & Purpose
- This is a backend-only, modular AI platform for automating influencer marketing campaigns.
- It exposes a FastAPI HTTP API, implements multi-agent orchestration (discovery, negotiation, contract) and integrates with external AI/voice services and a database.

##### Break Down the Core Architectural Layers
a. API Layer
- main.py / FastAPI app
- Routers: /api/webhooks, /api/monitor, plus “enhanced” variants
b. Orchestration Layer (Agents)
- orchestrator.py (master coordinator)
- discovery.py (creator matching)
- negotiation.py (voice-based deal closing)
- contracts.py (legal document generation)
- enhanced_* variants augment core agents
c. Service Layer
- database.py (persistence)
- embeddings.py (vector similarity)
- pricing.py (market data & rates)
- voice.py & enhanced_voice.py (ElevenLabs integration)
- conversation_monitor.py (real-time call tracking)
d. Data Layer
- Static files: data/creators.json, market_data.json, negotiation_tactis.txt
- Models: models/campaign.py (Pydantic schemas)
e. Config Layer
- config/settings.py (environment & feature flags)
f. External Integrations
- ElevenLabs API (voice calls)
- Groq API (AI strategy)
- Sentence Transformers (ML embeddings)
- PostgreSQL (optional, mocked by default)

##### Component Relationships & Data Flows
- Client → HTTP request → FastAPI router
- Router delegates to Orchestrator agent
- Orchestrator invokes:
– Discovery Agent → EmbeddingService → Sentence-Transformer → returns candidate list
– Negotiation Agent → VoiceService → ElevenLabs → live call transcripts
– Contracts Agent → (optionally PricingService → market_data) → generates contract document
- Each agent writes/reads state via DatabaseService
- Monitoring endpoints query DatabaseService or Agent state for real-time metrics
- Orchestrator collates results, returns final response or writes summary to DB

##### Architectural Patterns & Principles
- Layered Architecture: clear separation between API, Orchestrators (business logic), Services (infrastructure), Data
- Agent-Based Pipeline: each “phase” is encapsulated in its own agent class
- Asynchronous / Event-Driven: agents can run concurrently (asyncio.gather)
- Dependency Injection via config/settings
- Extensibility Points: enhanced_*.py modules, ability to add new agents or services

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client"]:::external

    subgraph "API Layer"
        API["FastAPI App (main.py)"]:::api
        Webhooks["/api/webhooks"]:::api
        Monitoring["/api/monitoring"]:::api
        EnhWebhooks["/api/enhanced-webhooks"]:::api
        EnhMonitoring["/api/enhanced-monitoring"]:::api
    end

    Client -->|"HTTP Request"| API
    API -->|"routes to"| Webhooks
    API -->|"routes to"| Monitoring
    API -->|"routes to"| EnhWebhooks
    API -->|"routes to"| EnhMonitoring

    subgraph "Agents Layer"
        Orchestrator["Orchestrator"]:::agent
        Disc["Discovery Agent"]:::agent
        Neg["Negotiation Agent"]:::agent
        Contr["Contracts Agent"]:::agent
        EnhOrch["Enhanced Orchestrator"]:::agent
        EnhNeg["Enhanced Negotiation"]:::agent
        EnhContr["Enhanced Contracts"]:::agent
    end

    Webhooks -->|"POST webhook"| Orchestrator
    EnhWebhooks -->|"POST enhanced webhook"| EnhOrch
    Monitoring -->|"GET /monitor"| Orchestrator
    EnhMonitoring -->|"GET /enhanced-monitor"| EnhOrch

    Orchestrator -->|"invoke"| Disc
    Orchestrator -->|"invoke"| Neg
    Orchestrator -->|"invoke"| Contr
    EnhOrch -->|"invoke"| EnhNeg
    EnhOrch -->|"invoke"| EnhContr

    subgraph "Services Layer"
        DBService["DatabaseService"]:::service
        Embed["EmbeddingService"]:::service
        Pricing["PricingService"]:::service
        Voice["VoiceService"]:::service
        EnhVoice["Enhanced VoiceService"]:::service
        ConvMon["ConversationMonitor"]:::service
        Config["Environment & Flags"]:::service
    end

    Disc -->|"getCreators()"| Embed
    Neg -->|"callElevenLabs()"| Voice
    Contr -->|"generateContract()"| Pricing
    Neg -->|"log call"| ConvMon
    EnhNeg -->|"callElevenLabs()"| EnhVoice

    DBService -->|"read/write"| DataStore
    Disc --> DBService
    Neg --> DBService
    Contr --> DBService
    EnhNeg --> DBService
    EnhContr --> DBService

    Config -.->|"feature flags"| API
    Config -.->|"feature flags"| Orchestrator

    subgraph "Data Layer"
        DataStore["PostgreSQL / File Mock"]:::data
        Creators["creators.json"]:::data
        Market["market_data.json"]:::data
        Tactics["negotiation_tactis.txt"]:::data
        Models["models/campaign.py"]:::data
    end

    DBService -->|"persist state"| DataStore
    Disc -->|"load static"| Creators
    Contr -->|"load static"| Market
    Neg -->|"load static"| Tactics
    Models -.-> Contr

    subgraph "External Integrations"
        Eleven["ElevenLabs API"]:::external
        Groq["Groq API"]:::external
        Transformers["Sentence-Transformers"]:::external
    end

    Embed -->|"embed()"| Transformers
    Voice -->|"API call"| Eleven
    EnhVoice -->|"API call"| Eleven
    Pricing -->|"fetchRates()"| Groq

    %% Click Events
    click API "https://github.com/wolfsbane9513/influencer-ai/blob/main/main.py"
    click Webhooks "https://github.com/wolfsbane9513/influencer-ai/blob/main/api/webhooks.py"
    click Monitoring "https://github.com/wolfsbane9513/influencer-ai/blob/main/api/monitoring.py"
    click EnhWebhooks "https://github.com/wolfsbane9513/influencer-ai/blob/main/api/enhanced_webhooks.py"
    click EnhMonitoring "https://github.com/wolfsbane9513/influencer-ai/blob/main/api/enhanced_monitoring.py"
    click Orchestrator "https://github.com/wolfsbane9513/influencer-ai/blob/main/agents/orchestrator.py"
    click Disc "https://github.com/wolfsbane9513/influencer-ai/blob/main/agents/discovery.py"
    click Neg "https://github.com/wolfsbane9513/influencer-ai/blob/main/agents/negotiation.py"
    click Contr "https://github.com/wolfsbane9513/influencer-ai/blob/main/agents/contracts.py"
    click EnhOrch "https://github.com/wolfsbane9513/influencer-ai/blob/main/agents/enhanced_orchestrator.py"
    click EnhNeg "https://github.com/wolfsbane9513/influencer-ai/blob/main/agents/enhanced_negotiation.py"
    click EnhContr "https://github.com/wolfsbane9513/influencer-ai/blob/main/agents/enhanced_contracts.py"
    click DBService "https://github.com/wolfsbane9513/influencer-ai/blob/main/services/database.py"
    click Embed "https://github.com/wolfsbane9513/influencer-ai/blob/main/services/embeddings.py"
    click Pricing "https://github.com/wolfsbane9513/influencer-ai/blob/main/services/pricing.py"
    click Voice "https://github.com/wolfsbane9513/influencer-ai/blob/main/services/voice.py"
    click EnhVoice "https://github.com/wolfsbane9513/influencer-ai/blob/main/services/enhanced_voice.py"
    click ConvMon "https://github.com/wolfsbane9513/influencer-ai/blob/main/services/conversation_monitor.py"
    click Creators "https://github.com/wolfsbane9513/influencer-ai/blob/main/data/creators.json"
    click Market "https://github.com/wolfsbane9513/influencer-ai/blob/main/data/market_data.json"
    click Tactics "https://github.com/wolfsbane9513/influencer-ai/blob/main/data/negotiation_tactis.txt"
    click Models "https://github.com/wolfsbane9513/influencer-ai/blob/main/models/campaign.py"
    click Config "https://github.com/wolfsbane9513/influencer-ai/blob/main/config/settings.py"

    classDef api fill:#D0E7FF,stroke:#0366D6,color:#0366D6;
    classDef agent fill:#DFFFE0,stroke:#2E8B57,color:#2E8B57;
    classDef service fill:#FFF5CC,stroke:#DAA520,color:#DAA520;
    classDef data fill:#E8E8E8,stroke:#696969,color:#696969;
    classDef external fill:#F3E0FF,stroke:#800080,color:#800080;
```
