# vibing-ai/verifact architecture

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

- Interactive diagram: https://gitdiagram.com/vibing-ai/verifact
- Repository: https://github.com/vibing-ai/verifact

## Overview

##### Project Type and Purpose
- VeriFact is a full-stack, open-source AI fact-checking platform.
- It combines an interactive web UI (via Chainlit), a REST API (via FastAPI), a multi-agent pipeline for claim detection, evidence gathering, verdict writing, and persistence layers (Supabase PGVector and Redis).

##### File Structure Analysis
- Top-level:
- app.py & chainlit.md – entry point for Chainlit UI
- src/main.py – FastAPI app entrypoint
- src/verifact_manager.py – CLI orchestrator of the agent pipeline
- src/verifact_agents/ – implementations of ClaimDetector, EvidenceHunter, VerdictWriter
- src/api/ – API endpoints (e.g., factcheck.py)
- src/models/ – Pydantic models for request/response schemas
- src/utils/logging/ – centralized logging configuration
- notebooks/ & examples/ – tutorials and usage samples
- Configuration:
- .env-example, .env (environment variables)
- pyproject.toml & uv.lock (dependency management via uv)
- pytest.ini (test settings)
- GitHub workflows for CI

##### Key Architectural Insights from README
- Multi-agent pipeline: ClaimDetector → EvidenceHunter → VerdictWriter
- UI: Chainlit for step-by-step interactive experience
- API Framework: FastAPI for programmatic access
- Model Access: OpenRouter (and optional OpenAI Agents SDK)
- Cache: Redis for model results & evidence caching
- Database: Supabase with PGVector for vector embeddings and session persistence

a. Main Components
1. UI Layer
- Chainlit Web App (app.py)
- User Authentication (Chainlit built-in auth)
2. API Layer
- FastAPI Server (src/main.py → src/api endpoints)
3. Orchestrator
- verifact_manager.py (CLI)
- Internal Agent Manager (coordinates agents)
4. Agents
- ClaimDetector (src/verifact_agents/claim_detector.py)
- EvidenceHunter (src/verifact_agents/evidence_hunter.py)
- VerdictWriter (src/verifact_agents/verdict_writer.py)
5. External Services
- OpenRouter (OpenAI, Anthropic, Mistral models)
- Optional Serper API (web search)
6. Persistence
- Supabase (PostgreSQL + PGVector)
- Redis Cache
7. Utilities
- Logging subsystem (src/utils/logging)
- Configuration (environment variables validated by Pydantic)

b. Relationships & Data Flow
1. User → Chainlit UI
- UI sends user input (text or document) to the backend via WebSocket or HTTP
2. UI / CLI → FastAPI / verifact_manager
- UI calls FastAPI endpoints or verifact_manager CLI triggers pipeline
3. Orchestrator → Agents
- Sequence: ClaimDetector extracts claims → EvidenceHunter fetches evidence → VerdictWriter generates verdict
4. Agents ↔ External Model APIs
- Each agent calls OpenRouter (and OpenAI Agents SDK where configured)
5. EvidenceHunter → Optional Serper / Web Search API
6. Agents ↔ Redis Cache
- Cache intermediate results, model outputs, evidence
7. Final Results → Supabase
- Session persistence, embeddings stored in PGVector
8. FastAPI → Supabase
- Retrieves past sessions, user data, cached vectors
9. UI displays results with source citations and explanations

c. Architectural Patterns & Principles
- Modular Pipeline: Each agent is a pluggable component
- Separation of Concerns: UI, API, Agents, Persistence, Caching
- Dependency Injection & Config Validation: Pydantic settings
- Extensibility Points:
- New agents under src/verifact_agents
- Swap model providers via environment variables

d. Key Technologies
- Python 3.10+, FastAPI, Chainlit
- OpenAI Agent SDK, OpenRouter (model gateway)
- Supabase (Postgres + PGVector)
- Redis for caching
- uv (poetry-like dependency manager)
- Pydantic for config and data models

##### Final Advice
- How environment configuration (env vars) feeds into all services.
- Detail data flows: user input → claim extraction → evidence retrieval → verdict generation → persistence → UI display.
- Do not over-simplify: the multi-agent structure and data stores are central to VeriFact’s architecture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UI["Chainlit Web App"]:::uiapi
        Doc["Chainlit Documentation"]:::uiapi
    end

    %% API / Control Plane
    subgraph "API / Control Plane"
        direction TB
        API["FastAPI Server"]:::uiapi
        Endpt["Fact-Check Endpoint"]:::uiapi
        CLI["VeriFact CLI Orchestrator"]:::uiapi
    end

    %% Processing Plane
    subgraph "Agent Pipeline" 
        direction TB
        CD["ClaimDetector Agent"]:::agents
        EH["EvidenceHunter Agent"]:::agents
        VW["VerdictWriter Agent"]:::agents
    end

    %% Utilities
    subgraph "Utilities & Config"
        direction TB
        Models["Pydantic Models"]:::utils
        Logging["Logging Config"]:::utils
        Env[".env-example"]:::utils
        Dep["pyproject.toml"]:::utils
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Redis["Redis Cache"]:::datastore
        PG["Supabase (Postgres + PGVector)"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        MR["Model Gateway (OpenRouter)"]:::external
        WS["Serper Web Search API"]:::external
    end

    %% Connections
    UI -->|"submits input"| API
    UI -->|"interactive docs"| Doc
    CLI -->|"triggers pipeline"| CD

    API -->|"routes to factcheck"| Endpt
    Endpt -->|"calls orchestrator"| CLI

    CLI -->|"run ClaimDetector"| CD
    CD -->|"extracts claims"| EH
    EH -->|"gather evidence"| VW
    VW -->|"generate verdict"| API

    CD -->|"calls model"| MR
    EH -->|"calls model"| MR
    VW -->|"calls model"| MR

    EH -->|"optional web search"| WS

    CD -->|"cache results"| Redis
    EH -->|"cache evidence"| Redis
    VW -->|"cache verdict"| Redis

    VW -->|"persist session"| PG
    API -->|"retrieve sessions"| PG

    Env --> UI
    Env --> API
    Env --> CLI
    Dep --> API
    Dep --> CLI
    Models --> Endpt
    Logging --> CLI
    Logging --> API

    %% Click Events
    click UI "https://github.com/vibing-ai/verifact/blob/main/app.py"
    click Doc "https://github.com/vibing-ai/verifact/blob/main/chainlit.md"
    click API "https://github.com/vibing-ai/verifact/blob/main/src/main.py"
    click Endpt "https://github.com/vibing-ai/verifact/blob/main/src/api/factcheck.py"
    click CLI "https://github.com/vibing-ai/verifact/blob/main/src/verifact_manager.py"
    click CD "https://github.com/vibing-ai/verifact/blob/main/src/verifact_agents/claim_detector.py"
    click EH "https://github.com/vibing-ai/verifact/blob/main/src/verifact_agents/evidence_hunter.py"
    click VW "https://github.com/vibing-ai/verifact/blob/main/src/verifact_agents/verdict_writer.py"
    click Models "https://github.com/vibing-ai/verifact/blob/main/src/models/factcheck.py"
    click Logging "https://github.com/vibing-ai/verifact/blob/main/src/utils/logging/logging_config.py"
    click Env "https://github.com/vibing-ai/verifact/blob/main/.env-example"
    click Dep "https://github.com/vibing-ai/verifact/blob/main/pyproject.toml"

    %% Styles
    classDef uiapi fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef agents fill:#90EE90,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef utils fill:#FFFACD,stroke:#333,stroke-width:1px
```
