# daudimwiti/qualagent-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/daudimwiti/qualagent-bridge
- Repository: https://github.com/daudimwiti/qualagent-bridge

## Overview

##### Project Type and Purpose
- QualAgents is primarily a backend service geared toward qualitative data analysis using AI. Its core functionality involves project management, agent orchestration for processing qualitative data, and generating insights. Despite being backend-focused, there is also a frontend component (built with TypeScript/React) used for visualizing and managing projects.
- The README confirms use of FastAPI, LangGraph (and LangChain), PostgreSQL with the pgvector extension, and Async SQLAlchemy to support an AI analysis pipeline.

##### Main Components
- API Layer:
- FastAPI endpoints (located in src/api/api_v1/ endpoints and api.py)
- Request validation via Pydantic schemas (in src/schemas)
- Authentication and middleware (as suggested by project structure)
- Service Layer:
- Business logic for handling projects, agents, and analysis (found in src/services, e.g., project_service.py, agent_service.py, analysis_service.py)
- Agent System:
- AI agents and the orchestrator (src/agents/orchestrator.py) that manage qualitative analysis tasks.
- Tools used per agent (under src/agents/tools such as sentiment_analysis.py, document_search.py, etc.)
- Data Processing / Analysis Pipeline:
- Steps that process qualitative data, perform sentiment analysis, theme clustering, and generate insights.
- Memory management and vector embeddings for semantic analysis (utilizing PostgreSQL with pgvector, referenced in src/core/embeddings.py and src/utils/vector_store.py).
- Database Layer:
- PostgreSQL database integration with the pgvector extension.
- Database models and initialization scripts (src/db/models.py and src/db/init_db.py) together with dependencies (src/db/dependencies.py).
- Frontend Component:
- React interface found in various TypeScript (.tsx) files under src/components and src/pages.
- Handles user interactions, project creation, configuration of agents, and result visualization.
- Deployment/Containerization:
- Docker file, docker-compose.yml, and associated scripts (entrypoint.sh) indicate containerized deployment.

##### Relationships and Interactions
- API calls from the frontend interact with the FastAPI backend. These endpoints handle requests such as creating projects, configuring agents, and retrieving analysis results.
- The API layer utilizes the Service Layer to apply business logic. The Service Layer further calls on the Agent System to orchestrate the data analysis pipeline.
- The Agent System processes raw qualitative data using its different tools (e.g., document_search, sentiment_analysis, theme_cluster) and consults persistent memory backed by the database.
- The Database Layer underpins storage for structured project data and vector embeddings for semantic similarity search.

##### Architectural Patterns and Design Principles
- Layered Architecture: Clearly separates the API, service, agent, and database layers.
- Component-Based Design: The frontend is modular (React components under src/components), which helps in understanding the separation of UI from business logic.
- Microservice or Modular RESTful Approach: While primarily a single service, the clear segmentation of API endpoints and services suggests a modular design approach.
- Containerization: Use of Docker ensures that the system’s components are containerized for easier deployment.

##### Relevant Technologies/Frameworks
- Backend: Python 3.11+, FastAPI, Async SQLAlchemy, LangGraph for agent orchestration, PostgreSQL along with pgvector.
- Frontend: React (TypeScript) with a rich component library (many UI components in src/components/ui).
- Containerization: Docker, Docker Compose.
- Scripting: Utility scripts and tools that assist with database initialization and caching are located in src/scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Deployment/Containerization"
        DEP["Docker & Containerization"]:::deployment
    end

    subgraph "Frontend UI"
        FE_APP["React Interface"]:::frontend
        FE_PAGES["Pages & Components"]:::frontend
    end

    subgraph "API Layer"
        API_E["FastAPI Endpoints"]:::api
        API_P["Pydantic Schemas"]:::api
    end

    subgraph "Service Layer"
        SER["Business Logic (Projects, Agents, Analysis)"]:::service
    end

    subgraph "Agent System"
        AG_ORCH["Agent Orchestrator"]:::agent
        AG_TOOLS["Agent Tools"]:::agent
    end

    subgraph "Data Processing"
        DP["Memory & Vector Embeddings"]:::dataprocess
    end

    subgraph "Database"
        DB["PostgreSQL DB (pgvector & Models)"]:::database
    end

    %% Connections
    DEP -->|"deploys"| FE_APP
    DEP -->|"deploys"| API_E
    DEP -->|"deploys"| SER
    DEP -->|"deploys"| AG_ORCH
    DEP -->|"deploys"| DB

    FE_APP -->|"API_calls"| API_E
    FE_PAGES -->|"API_calls"| API_E

    API_E -->|"triggers"| SER
    API_P -->|"validates"| SER

    SER -->|"orchestrates"| AG_ORCH
    SER -->|"processes"| DP
    SER -->|"stores_data"| DB

    AG_ORCH -->|"invokes_tools"| AG_TOOLS
    AG_ORCH -->|"reads/writes"| DB
    AG_TOOLS -->|"reads/writes"| DB

    DP -->|"embeds_data"| DB

    %% Click Events
    click API_E "https://github.com/daudimwiti/qualagent-bridge/blob/main/src/api/api_v1/api.py"
    click API_P "https://github.com/daudimwiti/qualagent-bridge/tree/main/src/schemas/"
    click SER "https://github.com/daudimwiti/qualagent-bridge/tree/main/src/services/"
    click AG_ORCH "https://github.com/daudimwiti/qualagent-bridge/blob/main/src/agents/orchestrator.py"
    click AG_TOOLS "https://github.com/daudimwiti/qualagent-bridge/tree/main/src/agents/tools/"
    click DP "https://github.com/daudimwiti/qualagent-bridge/blob/main/src/core/embeddings.py"
    click DB "https://github.com/daudimwiti/qualagent-bridge/blob/main/src/db/models.py"
    click FE_APP "https://github.com/daudimwiti/qualagent-bridge/blob/main/src/App.tsx"
    click DEP "https://github.com/daudimwiti/qualagent-bridge/tree/main/Dockerfile"

    %% Styles
    classDef frontend fill:#f9c,stroke:#333,stroke-width:2px;
    classDef api fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef service fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef agent fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef dataprocess fill:#e2e3e5,stroke:#333,stroke-width:2px;
    classDef database fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef deployment fill:#d1ecf1,stroke:#333,stroke-width:2px;
```
