# unclecode/doc2talk architecture

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

- Interactive diagram: https://gitdiagram.com/unclecode/doc2talk
- Repository: https://github.com/unclecode/doc2talk

## Overview

##### Project type and purpose
- Doc2Talk is a Python-based command-line tool and library that provides an interactive code-documentation chat interface.
- It combines a knowledge-graph index of your code and markdown docs with LLM calls for context decisions and response generation.

##### File structure
- Top level:
- docs/           → project documentation and usage examples
- src/doc2talk/   → core package modules
- tests/          → unit tests
- pyproject.toml  → build and dependency configuration
- Key modules under src/doc2talk:
- __main__.py & cli.py      → CLI entrypoint and argument parsing
- core.py & doc2talk.py     → Doc2Talk orchestration (indexing, chatting, session management)
- docgraph.py               → Knowledge-graph construction, BM25 search, serialization
- models.py                 → LLM configuration and wrappers
- Caching directories (not in this repo but described in README):
- ~/.doctalk/repos          → cloned GitHub repos
- ~/.doctalk/index          → serialized knowledge graphs
- ~/.doctalk/sessions       → saved chat sessions

##### README for additional insights
- Describes three main subsystems:
1. DocGraph knowledge-graph engine (indexing, BM25 search, serialization)
2. Contextual decision making (LLM for deciding when/how to update context)
3. Repository & index caching (file-system stores and lazy loading)
- Explains CLI and Python API usage, LLM configurations, and performance optimizations.

a. Main components
- User (Terminal)
- CLI Module
- Doc2Talk Core
- DocGraph Engine
- LLM Service(s)
- File-System Caches (Repos, Indexes, Sessions)
- External GitHub / Local Code + Docs
b. Relationships and data flow
1. User types a command in the terminal
2. CLI parses arguments and invokes Doc2Talk core
3. Core checks for cached repo/index; if missing, it:
- Clones or reads code/docs from GitHub or local path
- Calls DocGraph to build or load the knowledge graph
- Serializes graph into index cache
4. For each user query:
- Core sends “should update context?” to Context-Decision LLM
- If needed, DocGraph BM25-searches graph for relevant passages
- Core assembles context and calls Generation LLM for response
- Core writes/updates session file and streams response to user
c. Architectural patterns & design principles
- Modular layering: CLI → Core orchestration → DocGraph → LLM → Data caches
- Lazy initialization: index built on demand
- Separation of concerns: knowledge-graph logic isolated from LLM logic and I/O
- Cache-first approach: avoid repeated cloning or reindexing
d. Key technologies & libraries
- Python packaging (pyproject.toml)
- LLM interaction (openai or similar) via models.py
- BM25 search engine inside docgraph.py
- Serialization (optimized binary format, memory-mapped I/O)

##### Essential architectural elements
- Persistent caches’ lifecycle (read/write operations).
- Flow of data from code/docs → knowledge graph → LLM → user.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & Frontend
    User["User (Terminal)"]:::external
    subgraph "CLI Module"
        CLI_Main["__main__.py"]:::frontend
        CLI_CLI["cli.py"]:::frontend
    end

    %% Backend Core
    subgraph "Doc2Talk Core Package"
        Init["__init__.py"]:::core
        Core_Core["core.py"]:::core
        Core_Doc2Talk["doc2talk.py"]:::core
        DocGraph["docgraph.py"]:::core
        Models["models.py"]:::core
    end

    %% Caches
    subgraph "File-System Caches"
        ReposCache["Repos Cache (~/.doctalk/repos)"]:::datastore
        IndexCache["Index Cache (~/.doctalk/index)"]:::datastore
        SessionsCache["Sessions Cache (~/.doctalk/sessions)"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        GitHub["GitHub / Local Code"]:::external
        LLM["LLM API"]:::external
    end

    %% Supporting Docs & Config
    subgraph "Docs & Config"
        DocsFolder["docs/"]:::external
        Example1["simple_usage.py"]:::external
        Example2["advanced_usage.py"]:::external
        Example3["custom_models.py"]:::external
        Pyproject["pyproject.toml"]:::external
        TestCore["test_core.py"]:::external
        TestDoc2Talk["test_doc2talk.py"]:::external
        Changelog["CHANGELOG.md"]:::external
        Release["2025-03-14-v0.1.1.md"]:::external
    end

    %% Relationships
    User --> CLI_Main
    CLI_Main --> CLI_CLI
    CLI_CLI --> Init
    CLI_CLI --> Core_Core
    Core_Core --> Core_Doc2Talk
    Core_Doc2Talk -->|checks cache| ReposCache
    ReposCache -->|miss → clone/read| GitHub
    GitHub -->|store| ReposCache
    Core_Doc2Talk -->|build/load graph| DocGraph
    DocGraph -->|serialize| IndexCache
    IndexCache -->|load| DocGraph
    Core_Doc2Talk -->|context decision| Models
    Models -->|calls| LLM
    Core_Doc2Talk -->|generation| Models
    Core_Doc2Talk -->|update session| SessionsCache
    Core_Doc2Talk -->|stream response| User

    %% Docs & Config Links
    DocsFolder --> Example1
    DocsFolder --> Example2
    DocsFolder --> Example3
    Drive_Config --- Pyproject
    Drive_Tests --- TestCore
    Drive_Tests --- TestDoc2Talk
    Drive_Changelog --- Changelog
    Drive_Changelog --- Release

    %% Click Events
    click CLI_Main "https://github.com/unclecode/doc2talk/blob/main/src/doc2talk/__main__.py"
    click CLI_CLI "https://github.com/unclecode/doc2talk/blob/main/src/doc2talk/cli.py"
    click Core_Core "https://github.com/unclecode/doc2talk/blob/main/src/doc2talk/core.py"
    click Core_Doc2Talk "https://github.com/unclecode/doc2talk/blob/main/src/doc2talk/doc2talk.py"
    click DocGraph "https://github.com/unclecode/doc2talk/blob/main/src/doc2talk/docgraph.py"
    click Models "https://github.com/unclecode/doc2talk/blob/main/src/doc2talk/models.py"
    click Init "https://github.com/unclecode/doc2talk/blob/main/src/doc2talk/__init__.py"
    click DocsFolder "https://github.com/unclecode/doc2talk/tree/main/docs/"
    click Example1 "https://github.com/unclecode/doc2talk/blob/main/docs/examples/simple_usage.py"
    click Example2 "https://github.com/unclecode/doc2talk/blob/main/docs/examples/advanced_usage.py"
    click Example3 "https://github.com/unclecode/doc2talk/blob/main/docs/examples/custom_models.py"
    click Pyproject "https://github.com/unclecode/doc2talk/blob/main/pyproject.toml"
    click TestCore "https://github.com/unclecode/doc2talk/blob/main/tests/test_core.py"
    click TestDoc2Talk "https://github.com/unclecode/doc2talk/blob/main/tests/test_doc2talk.py"
    click Changelog "https://github.com/unclecode/doc2talk/blob/main/CHANGELOG.md"
    click Release "https://github.com/unclecode/doc2talk/blob/main/docs/releases/2025-03-14-v0.1.1.md"

    %% Styles
    classDef frontend fill:#D5E8FF,stroke:#004A99,color:#000
    classDef core fill:#E1FFD5,stroke:#339900,color:#000
    classDef datastore fill:#FFE6CC,stroke:#CC6600,color:#000
    classDef external fill:#F2F2F2,stroke:#666666,color:#000
```
