# rikhil-nell/voiceiq architecture

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

- Interactive diagram: https://gitdiagram.com/rikhil-nell/voiceiq
- Repository: https://github.com/rikhil-nell/voiceiq

## Overview

##### Project type and purpose
- VoiceIQ is a backend‐focused AI-powered call log processing service.
- It exposes a RESTful API (FastAPI) for ingesting audio, transcribing, sanitizing, analyzing, and persisting call logs, plus a chat interface for conversational insights.
- It integrates with external transcription APIs (e.g., Groq’s Whisper), AI models for analysis, and a Supabase database.

##### File structure
- Top‐level files:
- app.py: Defines FastAPI endpoints.
- main.py: Orchestrates end-to-end workflow (transcribe → analyze → store).
- transcription.py: Audio ingestion, transcription calls, sanitization.
- agents.py: Implements AI agents (call log, report, database, chat).
- database.py: Wraps Supabase CRUD operations.
- memory.py: Manages state/memory for chat sessions.
- settings.py: Loads environment configuration (.env).
- prompts/: Stores prompt templates for each agent.
- Dockerfile, requirements.txt, pyproject.toml: Build and dependency definitions.

##### README
- The README confirms:
- Four AI agents each handling a specific task.
- Endpoints: /create_log, /logs/all, /logs/columns, /logs/report, /chat.
- Uses Supabase for persistence.
- External APIs for transcription and AI analysis.

##### Components
a. Client / Consumer
- Could be a web UI, CLI, or any HTTP client sending requests to the FastAPI server.
b. API Layer (FastAPI)
- app.py exposes endpoints; uvicorn serves.
c. Orchestration Layer
- main.py coordinates the workflow for /create_log:
1. transcription.py → external transcription API → raw transcript
2. Sanitization module within transcription.py → cleaned text
3. agents.py invokes:
- Call Log Agent (formatting)
- Report Agent (structured summary)
- Database Agent (extract actionable insights)
4. database.py persists final records in Supabase
- For /chat:
- memory.py retrieves session context
- chat agent in agents.py processes user prompt + context
d. Data Layer
- Supabase Database: tables for call logs, metadata, reports, perhaps memory…
e. External Services
- Transcription API (Groq’s Whisper or similar)
- AI Model API(s) for agent processing (OpenAI, etc.)
- Supabase REST/SDK endpoints

##### Relationships and interactions
- Client → HTTP → FastAPI (app.py)
- FastAPI endpoint (/create_log) → main.py workflow
- main.py → transcription.py → External Transcription API
- transcription.py → returns sanitized transcript → main.py
- main.py → agents.py for each agent → AI Model APIs
- agents.py → returns enriched data → main.py
- main.py → database.py → Supabase → confirmation → FastAPI → client
- For /chat: Client → app.py → agents.py + memory.py → AI Models → client

##### Architectural patterns and design principles
- Modular separation:
- API layer (app.py)
- Orchestration layer (main.py)
- Transcription & Sanitization (transcription.py)
- AI business logic (agents.py)
- Persistence (database.py)
- Session state (memory.py)
- Dependency injection via settings.py for environment/config
- Use of prompt templates in a separate folder for easy maintenance
- Single Responsibility Principle: each module has a clear, distinct role
- Externalize secrets and configs to .env (settings.py)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["Client (Web UI/CLI)"]:::client

    %% API Layer
    subgraph "API Layer"
        API["app.py"]:::internal
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        Orch["main.py"]:::internal
        Trans["transcription.py"]:::internal
        Agents["agents.py"]:::internal
        subgraph "Prompt Templates"
            CLP["call_log_agent_prompt.txt"]:::internal
            RRP["report_agent_prompt.txt"]:::internal
            DBP["database_agent_prompt.txt"]:::internal
            CHP["chat_agent_prompt.txt"]:::internal
        end
    end

    %% Session State
    subgraph "Session Layer"
        Mem["memory.py"]:::internal
    end

    %% Persistence Module
    subgraph "Persistence Layer"
        Pers["database.py"]:::internal
        DB[(Supabase DB)]:::data
    end

    %% Config & DevOps
    subgraph "Config & DevOps"
        Settings["settings.py"]:::internal
        Docker["Dockerfile"]:::internal
        Req["requirements.txt"]:::internal
        Pyproj["pyproject.toml"]:::internal
    end

    %% External Services
    subgraph "External Services"
        TransAPI["Transcription API"]:::external
        AIAPI["AI Model API"]:::external
    end

    %% Data Flows
    Client -->|"HTTP/JSON"| API
    API -->|"invoke workflow"| Orch
    Orch -->|"1. transcribe audio"| Trans
    Trans -->|"REST/JSON"| TransAPI
    TransAPI -->|"raw transcript"| Trans
    Trans -->|"sanitized text"| Orch
    Orch -->|"2. call log formatting"| Agents
    Orch -->|"3. summary report"| Agents
    Orch -->|"4. actionable insights"| Agents
    Agents -->|"AI requests"| AIAPI
    AIAPI -->|"AI responses"| Agents
    Agents -->|"formatted output"| Orch
    Orch -->|"persist data"| Pers
    Pers -->|"SQL/CRUD"| DB
    DB -->|"confirmation"| Pers
    Pers -->|"response"| Orch
    Orch -->|"final response"| API
    API -->|"HTTP/JSON"| Client

    %% Chat Flow
    Client -->|"HTTP/JSON /chat"| API
    API -->|"retrieve memory"| Mem
    API -->|"chat request"| Agents
    Mem -->|"session context"| Agents
    Agents -->|"AI chat"| AIAPI
    AIAPI -->|"chat response"| Agents
    Agents -->|"reply"| API
    API -->|"HTTP/JSON"| Client

    %% Click Events
    click API "https://github.com/rikhil-nell/voiceiq/blob/master/app.py"
    click Orch "https://github.com/rikhil-nell/voiceiq/blob/master/main.py"
    click Trans "https://github.com/rikhil-nell/voiceiq/blob/master/transcription.py"
    click Agents "https://github.com/rikhil-nell/voiceiq/blob/master/agents.py"
    click CLP "https://github.com/rikhil-nell/voiceiq/blob/master/prompts/call_log_agent_prompt.txt"
    click RRP "https://github.com/rikhil-nell/voiceiq/blob/master/prompts/report_agent_prompt.txt"
    click DBP "https://github.com/rikhil-nell/voiceiq/blob/master/prompts/database_agent_prompt.txt"
    click CHP "https://github.com/rikhil-nell/voiceiq/blob/master/prompts/chat_agent_prompt.txt"
    click Pers "https://github.com/rikhil-nell/voiceiq/blob/master/database.py"
    click Mem "https://github.com/rikhil-nell/voiceiq/blob/master/memory.py"
    click Settings "https://github.com/rikhil-nell/voiceiq/blob/master/settings.py"
    click Docker "https://github.com/rikhil-nell/voiceiq/tree/master/Dockerfile"
    click Req "https://github.com/rikhil-nell/voiceiq/blob/master/requirements.txt"
    click Pyproj "https://github.com/rikhil-nell/voiceiq/blob/master/pyproject.toml"

    %% Styles
    classDef client fill:#ffeb3b,stroke:#333,stroke-width:1px
    classDef internal fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef data fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#333,stroke-width:1px
```
