# ak1484/git_doc architecture

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

- Interactive diagram: https://gitdiagram.com/ak1484/git_doc
- Repository: https://github.com/ak1484/git_doc

## Overview

##### Project Type and Purpose
- This is an open-source, command-line documentation generator tool.
- It automatically downloads or reads a code repository, parses its files, uses OpenAI (via LangChain) to generate per‐file documentation, stores the results in a FAISS vector database, and produces (or updates) a final Markdown document.

##### High-Level Architecture Components
a. CLI / Entry Point (main.py)
- Parses user arguments (local path vs. GitHub URL, mode, output directory, API key).
- Coordinates the overall workflow.
b. Repository Acquisition
- download_repo.py – clones a GitHub repo when needed.
- (Or direct file system access for a local path.)
c. Repository Parser (repo_parser.py)
- Walks the directory tree.
- Extracts file metadata and contents.
d. Documentation Generator (doc_generator.py & final_doc_generator.py)
- Uses OpenAI + LangChain to produce doc snippets per file.
- final_doc_generator.py merges snippets into a cohesive Markdown file.
e. Vector Store (vector_store.py & doc_storage.py)
- Wraps FAISS for indexing and retrieving documentation embeddings.
- Supports lookup/update of doc vectors.
f. Updater (updater.py)
- Detects changed files since last run.
- Re-generates docs only for those files.
g. Output (example_usage.py is sample client code; main.py drives actual runs)
- Writes final Markdown doc tree to disk.
- Persists FAISS database files under output_dir.

##### Data Flow and Interactions
1. User invokes main.py → argument parser
2. main imports/executes download_repo or skips to repo_parser
3. repo_parser emits a file list + contents
4. For each file:
– doc_generator calls OpenAI API via LangChain → returns doc snippet
– vector_store adds/updates FAISS embedding
5. Once all snippets are processed:
– final_doc_generator collates snippets into one .md
– updater (in “update” mode) diffs file list, re-calls doc_generator & vector_store on changed files only
6. Output directory populated with:
– FAISS index files
– final Markdown documentation

##### Architectural Patterns & Design Principles
- Pipeline pattern: clear separation of “Acquire → Parse → Generate → Store → Collate.”
- Single Responsibility per module (each .py focuses on one stage).
- Pluggable storage (vector_store abstraction over FAISS).
- Incremental update logic in updater.py (avoid full reprocessing).
- External integrations as well‐defined services (OpenAI API, GitHub).

##### Technologies & Frameworks
- Python 3.x
- OpenAI API + LangChain library
- FAISS (vector similarity search)
- GitPython or subprocess git calls (download_repo.py)
- Markdown output

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI["main.py"]:::cli
        ExampleClient["example_usage.py"]:::cli
    end

    %% Acquisition Layer
    subgraph "Acquisition Layer"
        direction TB
        Download["download_repo.py"]:::acq
        LocalFS["Local File System"]:::acq
        GitHub(("GitHub")):::external
    end

    %% Processing Layer
    subgraph "Processing & Generation Layer"
        direction TB
        Parser["repo_parser.py"]:::proc
        DocGen["doc_generator.py"]:::proc
        Updater["updater.py"]:::proc
        FinalCollator["final_doc_generator.py"]:::proc
    end

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        VectorDB[(FAISS DB)]:::storage
        DocStore[(doc_storage.py)]:::storage
        FinalMD[(Final Markdown .md)]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI(("OpenAI API")):::external
    end

    %% Connections
    CLI -->|parses args| Download
    CLI -->|parses args| LocalFS
    CLI --> ExampleClient
    Download -->|git clone| GitHub
    Download -->|repo files| Parser
    LocalFS -->|local files| Parser
    Parser -->|file list + contents| DocGen
    DocGen -->|doc snippet| VectorDB
    DocGen -->|doc snippet| DocStore
    DocGen -->|calls OpenAI| OpenAI
    VectorDB -->|stores embedding| DocStore
    DocStore -->|stores embedding| VectorDB
    DocGen --> FinalCollator
    Updater -->|detects changes| DocGen
    FinalCollator -->|final markdown| FinalMD

    %% Update Mode Loop
    FinalCollator -->|incremental update| Updater
    Updater -->|changed files| DocGen

    %% Arrow Labels
    Parser -->|"file data"| DocGen
    DocGen -->|"vector embed"| VectorDB
    FinalCollator -->|"collate snippets"| FinalMD

    %% Click Events
    click CLI "https://github.com/ak1484/git_doc/blob/main/main.py"
    click ExampleClient "https://github.com/ak1484/git_doc/blob/main/example_usage.py"
    click Download "https://github.com/ak1484/git_doc/blob/main/download_repo.py"
    click Parser "https://github.com/ak1484/git_doc/blob/main/repo_parser.py"
    click DocGen "https://github.com/ak1484/git_doc/blob/main/doc_generator.py"
    click FinalCollator "https://github.com/ak1484/git_doc/blob/main/final_doc_generator.py"
    click VectorDB "https://github.com/ak1484/git_doc/blob/main/vector_store.py"
    click DocStore "https://github.com/ak1484/git_doc/blob/main/doc_storage.py"
    click Updater "https://github.com/ak1484/git_doc/blob/main/updater.py"

    %% Styles
    classDef cli fill:#D6EAF8,stroke:#2980B9,stroke-width:1px
    classDef acq fill:#D5F5E3,stroke:#239B56,stroke-width:1px
    classDef proc fill:#EBDEF0,stroke:#8E44AD,stroke-width:1px
    classDef storage fill:#FDEDEC,stroke:#C0392B,stroke-width:1px
    classDef external fill:#F4F6F7,stroke:#7F8C8D,stroke-width:1px,stroke-dasharray: 5 5
```
