# seelebrn/deep-research-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/seelebrn/deep-research-v2
- Repository: https://github.com/seelebrn/deep-research-v2

## Overview

##### Project Type and Purpose
- This is a Python-based research automation system (CLI tool) that orchestrates AI/ML models, academic database integrations, semantic storage, and an interactive chat interface.
- Its purpose is to take a user’s research query, break it down, search multiple academic and web sources, filter and compress content, store results in ChromaDB, and generate structured reports with citations.

##### File Structure
- Top-level scripts:
- start.py – primary entry point
- main.py – CLI interface for research pipelines and DB management
- knowledge_chat.py – interactive chat against persisted knowledge
- deep_research.py – orchestrator of the research pipeline
- academia.py – connectors to PubMed, HAL, arXiv, CrossRef, PEPITE
- deep_storage.py – ChromaDB persistence layer
- other scripts (debug.py, report_quality_enhancer.py, etc.) augment research flows
- Configuration / setup:
- .env.template / env.template – environment variables for model URLs, API keys, thresholds
- requirements.txt – Python dependencies (spaCy, chromadb, requests, OpenAI/LM SDK)
- Installer.bat – one-click installer on Windows
- setup.md – setup instructions
- External folders (implied by README):
- DBs/ – local vector databases per knowledge domain
- research_export_*/ – generated reports and export artifacts

##### Extract Architectural Insights from README
- Core pipeline stages:
1. Query Analysis
2. Multi-Cycle Source Discovery
3. Semantic Filtering & Compression
4. Knowledge Persistence (ChromaDB)
5. Synthesis & Export (reports, citations)
- Feedback loop for iterative refinement
- Integration points:
- LM Studio / OpenAI-like local server
- Search API (SearXNG)
- Academic database APIs
- spaCy for NLP
- ChromaDB for vector storage

##### Main Components and Their Interactions
a. User Interface
- CLI (start.py, main.py)
- knowledge_chat.py for interactive queries
b. Core Orchestrator
- deep_research.py invokes sub-modules for each pipeline stage
c. Academic Integrations
- academia.py calls external APIs for source discovery
d. Semantic Processing
- spaCy for keyword extraction
- deep_research.py and helper scripts for compression, verification
e. Persistence Layer
- deep_storage.py interacts with ChromaDB
f. External Services
- LM Studio / OpenAI server for generation and filtering models
- SearXNG (search API)
- Academic web APIs (PubMed, HAL, etc.)
g. Data Stores
- Local vector DBs (./DBs/{name}_knowledge_db/)
- Exported report files (research_export_*/)

##### Architectural Patterns and Design Principles
- Pipeline pattern: sequential stages with feedback loops
- Modular integration: separate modules for search, NLP, storage, synthesis
- Dependency injection via environment variables and CLI flags
- Layered architecture:
- Presentation (CLI)
- Application (orchestration)
- Domain (research logic, NLP)
- Infrastructure (storage, external APIs)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UI_CLI1["start.py (Entry Point)"]:::presentation
        UI_CLI2["main.py (CLI & DB Mgmt)"]:::presentation
        UI_Chat["knowledge_chat.py (Interactive Chat)"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        Orchestrator["deep_research.py (Orchestrator)\nConfig via .env & CLI flags"]:::application
        Debugger["debug.py (Debug & Inspection)"]:::application
        Quality["report_quality_enhancer.py (Semantic Processing)"]:::application
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        subgraph "Academic Integrations"
            direction TB
            Academia["academia.py\n(PubMed, arXiv, HAL, CrossRef, PEPITE)"]:::external
            AcademicAPIs["Academic DB APIs"]:::external
        end
        subgraph "External Services"
            direction TB
            LM["LM Studio / OpenAI"]:::external
            SearchAPI["SearXNG Search API"]:::external
        end
        subgraph "Persistence"
            direction TB
            StorageLayer["deep_storage.py (ChromaDB)"]:::infrastructure
            VectorDB["ChromaDB Instances\n(./DBs/*_knowledge_db/)"]:::database
        end
    end

    %% Export Layer
    subgraph "Export Layer"
        direction TB
        ExportFiles["research_export_* (Report Files)"]:::database
    end

    %% Connections
    UI_CLI1 -->|invokes| Orchestrator
    UI_CLI2 -->|invokes| Orchestrator
    UI_Chat -->|queries| StorageLayer

    Orchestrator -->|source discovery| Academia
    Academia -->|fetches| AcademicAPIs
    Orchestrator -->|semantic filter| Quality
    Quality -->|optional feedback| Orchestrator
    Orchestrator -->|persist knowledge| StorageLayer
    StorageLayer -->|stores vectors| VectorDB
    Orchestrator -->|synthesize reports| ExportFiles
    ExportFiles -->|feedback loop| Orchestrator
    Orchestrator -->|calls model| LM
    Orchestrator -->|search API| SearchAPI

    Academia -->|iterative loop| Orchestrator

    %% Legend
    subgraph "Legend"
        direction TB
        A["Rectangle: Modules"]:::legend
        B["Cylinder: Databases/Files"]:::legend
        C["Cloud: External Services/APIs"]:::legend
    end

    %% Click Events
    click UI_CLI1 "https://github.com/seelebrn/deep-research-v2/blob/main/start.py"
    click UI_CLI2 "https://github.com/seelebrn/deep-research-v2/blob/main/main.py"
    click UI_Chat "https://github.com/seelebrn/deep-research-v2/blob/main/knowledge_chat.py"
    click Orchestrator "https://github.com/seelebrn/deep-research-v2/blob/main/deep_research.py"
    click Academia "https://github.com/seelebrn/deep-research-v2/blob/main/academia.py"
    click StorageLayer "https://github.com/seelebrn/deep-research-v2/blob/main/deep_storage.py"
    click Quality "https://github.com/seelebrn/deep-research-v2/blob/main/report_quality_enhancer.py"
    click Debugger "https://github.com/seelebrn/deep-research-v2/blob/main/debug.py"
    click Env1 "https://github.com/seelebrn/deep-research-v2/blob/main/.env.template"
    click Env2 "https://github.com/seelebrn/deep-research-v2/blob/main/env.template"
    click Installer "https://github.com/seelebrn/deep-research-v2/blob/main/Installer.bat"
    click Requirements "https://github.com/seelebrn/deep-research-v2/blob/main/requirements.txt"
    click Setup "https://github.com/seelebrn/deep-research-v2/blob/main/setup.md"
    click License "https://github.com/seelebrn/deep-research-v2/tree/main/LICENSE"
    click Readme "https://github.com/seelebrn/deep-research-v2/blob/main/Readme.md"

    %% Styles
    classDef presentation fill:#cce5ff,stroke:#004085,color:#004085
    classDef application fill:#d4edda,stroke:#155724,color:#155724
    classDef infrastructure fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
    classDef database fill:#f1f1f1,stroke:#333333,color:#333333
    classDef legend fill:#ffffff,stroke:#000000,color:#000000
    class Env1,Env2,Installer,Requirements,Setup,License,Readme legend
```
