# keltoumboukra/twindoc architecture

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

- Interactive diagram: https://gitdiagram.com/keltoumboukra/twindoc
- Repository: https://github.com/keltoumboukra/twindoc

## Overview

##### Major Components
- Frontend/UI:
- There are two similar directories (“front-end” and “frontend”) that provide the web interface. The Streamlit–based “frontend/app.py” is used to launch an interactive web interface where users (clinicians) can enter queries and view transcripts, thinking processes, and final responses.
- Backend – Orchestration & Agents:
- The “agents” directory contains multiple Python modules such as orchestrator.py, medical_query.py, reza.py, reza_evaluator.py, reza_thinking.py, and reza_transcript.py. These files collectively implement the multi–agent system. The orchestrator acts as the central coordinator that delegates tasks to individual agents (e.g., TranscriptAgent, ThinkingAgent, RezaAgent) that process the incoming medical queries.
- Data Storage & Knowledge Base:
- There are “vectordb” folders (both at the root and inside agents) along with a “knowledge” directory that store vector representations as “.lance” files and related data. This suggests that the system uses a specialized vector database (built with Lancedb/tantivy) to keep track of historical queries, digital twin data, or intermediate reasoning processes.
- External Services & APIs:
- TwinDoc integrates external APIs: the Gemini API (primary) and OpenAI API (fallback). These external services are essential for performing the AI-driven query processing.
- Logging & Monitoring:
- The project integrates Weights & Biases (W&B) extensively. There are dedicated directories (e.g., “agents/wandb” and “wandb” at project root) for logging, which indicates that every query, agent activity, and response is logged for analysis and performance monitoring.
- Error Handling:
- The code includes robust error handling and retry mechanisms (as noted in the README and implied in the file structure via testing modules and scripts such as test_queries).

##### Relationships and Data Flow
- User Interaction:
- The front-end (Streamlit UI) accepts medical queries from users.
- Query Routing:
- Queries go to the orchestrator (from agents/orchestrator.py), which coordinates between various specialized agents.
- Agent Interactions:
- The Orchestrator delegates to the Transcript Agent, Thinking Agent (that might also include a DuckDuckGo integration or similar lookup), and Reza Agent, which together produce transcript context, reasoning (thinking process), and final responses.
- Data Storage:
- Some agents read/write to the vector databases in “vectordb” or “knowledge” directories, where intermediate representations (like “reza_thinking_process.lance” or “reza_knowledge.lance”) are stored.
- External API Communication:
- During processing, agents route requests to external AI services (Gemini/OpenAI) for generating responses.
- Logging & Monitoring:
- Throughout the process, interactions and errors are recorded to the W&B logs, and the Weave logger (weave_logger.py) might also capture certain logging information.

##### Architectural Patterns and Design Principles
- Multi–Agent Orchestration:
- The system is based on a multi–agent architecture. Each agent has a dedicated responsibility (i.e., transcript extraction, reasoning, final response formulation) and the orchestrator aggregates the outputs.
- Separation of Concerns:
- Frontend and backend components are clearly separated, as are the different logic modules (e.g., different agents, logging, and knowledge management).
- Robust Error Handling & Resilience:
- The system is designed with automatic retries (for API rate limits and service interruptions) and graceful degradation in mind.

##### Relevant Technologies
- Programming Language: Python 3.8+
- Frameworks/Libraries:
- Agno for AI agent framework integration.
- Streamlit for the web interface.
- Lancedb and Tantivy for vector database management.
- SQLAlchemy for database interactions (if applicable).
- Weights & Biases (W&B) for logging and monitoring.
- Additional libraries include tenacity (for retries) and python-dotenv (for environment management).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend/UI
    subgraph "Frontend/UI"
        A("Streamlit UI"):::frontend
        B("Web Interface Assets"):::frontend
    end

    %% Backend Orchestration & Agents
    subgraph "Backend Orchestration & Agents"
        C("Backend Orchestrator"):::backend
        subgraph "Agents"
            D("Medical Query Agent"):::backend
            E("Reza Agent"):::backend
            F("Reza Evaluator"):::backend
            G("Reza Thinking Agent"):::backend
            H("Reza Transcript Agent"):::backend
            I("Playground/Testing Agent"):::backend
            J("Test Queries"):::backend
        end
    end

    %% Data Storage & Knowledge Base
    subgraph "Data Storage & Knowledge Base"
        K("Vector DB: Thinking Processes"):::database
        L("Vector DB: Knowledge"):::database
        M("Knowledge Data"):::database
    end

    %% External Services & APIs
    subgraph "External Services & APIs"
        N("Gemini API"):::external
        O("OpenAI API"):::external
    end

    %% Logging & Monitoring
    subgraph "Logging & Monitoring"
        P("W&B (Agents)"):::logging
        Q("W&B (Global)"):::logging
        R("Weave Logger"):::logging
    end

    %% Error Handling
    subgraph "Error Handling"
        S("Testing/Error Handling Scripts"):::error
    end

    %% Connections: Frontend to Backend
    A -->|"query"| C
    B -->|"serve"| A

    %% Connections: Orchestrator to Agents
    C -->|"dispatch"| D
    C -->|"dispatch"| E
    C -->|"dispatch"| F
    C -->|"dispatch"| G
    C -->|"dispatch"| H
    C -->|"dispatch"| I
    C -->|"dispatch"| J

    %% Agent to External Services interactions
    D -->|"api_req"| N
    E -->|"api_req"| N
    E -->|"fallback"| O
    F -->|"api_req"| O
    G -->|"knowledge_update"| K
    H -->|"knowledge_update"| L

    %% Agents and Orchestrator log activities
    C -->|"log_data"| P
    D -->|"log_data"| P
    E -->|"log_data"| P
    F -->|"log_data"| P
    G -->|"log_data"| P
    H -->|"log_data"| P
    I -->|"log_data"| P
    J -->|"log_data"| P

    %% Global logging links
    C -->|"log"| Q
    D -->|"log"| Q
    E -->|"log"| Q
    F -->|"log"| Q
    G -->|"log"| Q
    H -->|"log"| Q
    I -->|"log"| Q
    J -->|"log"| Q
    P -->|"log"| R

    %% Orchestrator error handling
    C -->|"error_handling"| S

    %% Data Storage access from Agents
    G -->|"read/write"| M

    %% Class Definitions
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef database fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef external fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef logging fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef error fill:#FFB6C1,stroke:#000,stroke-width:2px;

    %% Click Events
    click A "https://github.com/keltoumboukra/twindoc/blob/main/frontend/app.py"
    click B "https://github.com/keltoumboukra/twindoc/tree/main/front-end/app"
    click C "https://github.com/keltoumboukra/twindoc/blob/main/agents/orchestrator.py"
    click D "https://github.com/keltoumboukra/twindoc/blob/main/agents/medical_query.py"
    click E "https://github.com/keltoumboukra/twindoc/blob/main/agents/reza.py"
    click F "https://github.com/keltoumboukra/twindoc/blob/main/agents/reza_evaluator.py"
    click G "https://github.com/keltoumboukra/twindoc/blob/main/agents/reza_thinking.py"
    click H "https://github.com/keltoumboukra/twindoc/blob/main/agents/reza_transcript.py"
    click I "https://github.com/keltoumboukra/twindoc/blob/main/agents/playground.py"
    click J "https://github.com/keltoumboukra/twindoc/blob/main/agents/test_queries.py"
    click K "https://github.com/keltoumboukra/twindoc/blob/main/vectordb/reza_thinking_process.lance"
    click L "https://github.com/keltoumboukra/twindoc/blob/main/vectordb/reza_knowledge.lance"
    click M "https://github.com/keltoumboukra/twindoc/tree/main/knowledge/reza"
    click P "https://github.com/keltoumboukra/twindoc/tree/main/agents/wandb"
    click Q "https://github.com/keltoumboukra/twindoc/tree/main/wandb"
    click R "https://github.com/keltoumboukra/twindoc/blob/main/weave_logger.py"
    click S "https://github.com/keltoumboukra/twindoc/blob/main/tests/test_orchestrator.py"
```
