# jerrylususu/code2prompt architecture

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

- Interactive diagram: https://gitdiagram.com/jerrylususu/code2prompt
- Repository: https://github.com/jerrylususu/code2prompt

## Overview

##### Project Type and Purpose
- This is a pure front-end web application that converts a Git repository (via a ZIP upload or GitHub URL) into a structured text representation. The text is formatted specifically for use with large language models (LLMs) and includes both the repository’s hierarchy and file content.
- The README emphasizes in-browser processing with no server-side requirements; all processing, parsing, file handling, and output generation happens on the client side.

##### File Structure
- The top-level files include index.html (entry point), a CSS file for styling, and a LICENSE and README. The JavaScript folder contains all application logic divided into multiple modules:
- js/editorHandler.js: Manages file preview/editing (likely powered by the Monaco Editor as mentioned).
- js/fileTree.js: Implements the interactive file tree view.
- js/githubHandler.js: Handles the fetching of repositories via GitHub URLs (if used).
- js/zipHandler.js: Deals with ZIP file processing using JSZip.
- js/textGenerator.js: Generates the formatted text output with the repository outline and file content.
- js/utils.js, uiHelpers.js, theme.js, debug.js, main.js: Utilities, UI support, theming, debugging, and central application control.
- This modular structure suggests clear separation between input processing (uploading and repository fetching), file/structure handling, UI operations, and output generation.

##### Examining the README for Additional Insights
- The README describes multiple key steps: repository input processing, file analysis and filtering (including binary file detection), tree visualization, token count estimation, file preview, text generation, and final output handling.
- It also lists the external libraries in use: JSZip for ZIP processing, FileSaver.js for file downloads, and tiktoken for token counting.
- No server-side processing means that the entire system is implemented as a client-side application, with the various JS modules orchestrating these functions.

a. Main Components:
- User Interface (UI):
- index.html and styles.css form the basis of the UI.
- Components: Input form, file tree view, preview modal (Monaco Editor).
- Input Handling Module:
- GitHub URL input and/or ZIP file upload.
- Modules: githubHandler.js and zipHandler.js.
- File Analysis and Tree Construction:
- Use fileTree.js to present an interactive, hierarchical file selection interface.
- Filtering mechanisms (binary file exclusion, hidden files).
- Processing and Text Generation:
- textGenerator.js handles converting the file tree and file content into the specified text format for LLMs.
- Utilizes utils.js for common functionalities.
- Token Estimation:
- Integration of tiktoken to estimate token counts per file and overall.
- Likely tied closely with text generation and the file analysis modules.
- File Preview and Editing:
- editorHandler.js provides functionality for users to preview/edit file content before inclusion.
- Output Handling:
- Mechanism for copying to clipboard or downloading the generated text as a file using FileSaver.js.

b. Relationships and Interactions:
- From the UI, events trigger the input handling modules (githubHandler.js and zipHandler.js) to retrieve the repository data.
- The retrieved files are passed to the file analysis component (fileTree.js) where the hierarchical view is built and files are filtered.
- User selection within the file tree is then passed to the processing layer (textGenerator.js) to produce the formatted text.
- Alongside, token estimation is triggered (utilizing tiktoken) to provide real-time feedback.
- Before finalization, users can preview/edit file content using the preview modal (editorHandler.js).
- Finally, the output component provides options to copy the text or download via FileSaver.js.
- Utility modules (uiHelpers.js, utils.js, theme.js, debug.js, main.js) support these flows by handling shared tasks, events, and configuration.

c. Important Architectural Patterns/Design Principles:
- Modular architecture: Each JS file encapsulates a distinct piece of functionality.
- Separation of concerns: Distinct components for input, processing, UI management, and output handling ensure easier maintainability.
- Client-side processing: All logic runs in the browser, simplifying deployment and increasing privacy.
- Event-driven interactions: User actions in the UI trigger specific processing pipelines (from file upload to text generation).

d. Relevant Technologies, Frameworks, or Libraries:
- Pure HTML, CSS, and JavaScript (no build steps or additional frameworks).
- External libraries: JSZip for ZIP handling, FileSaver.js for output download, and tiktoken for token estimation.
- The use of a Monaco Editor (implied in file preview) for code file preview.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    U("User"):::ui

    %% User Interface Subgraph
    subgraph "User Interface"
        UI1("index.html"):::ui
        UI2("styles.css"):::ui
    end

    %% Input Handling Subgraph
    subgraph "Input Handling"
        GHP("GitHub Handler"):::proc
        ZH("ZIP Handler"):::proc
    end

    %% File Analysis & Processing
    FT("File Tree"):::proc
    TG("Text Generator"):::proc
    EH("Editor Handler"):::proc
    OP("Output Handler"):::proc

    %% External Libraries
    JSZip("JSZip"):::ext
    Tiktoken("tiktoken"):::ext
    FileSaver("FileSaver.js"):::ext

    %% Utility Modules Subgraph
    subgraph "Utility Modules"
        UT("utils.js"):::util
        UH("uiHelpers.js"):::util
        TM("theme.js"):::util
        DB("debug.js"):::util
        MN("main.js"):::util
    end

    %% Data Flow
    U --> UI1
    U --> UI2

    UI1 --> GHP
    UI2 --> GHP
    UI1 --> ZH
    UI2 --> ZH

    GHP --> FT
    ZH --> FT
    ZH --> JSZip

    FT --> TG
    TG --> Tiktoken
    TG --> EH
    EH --> OP
    OP --> FileSaver

    %% Utility Support (dashed lines)
    UT --- FT
    UT --- TG
    UT --- EH
    UT --- GHP
    UT --- ZH
    UH --- FT
    UH --- TG
    TM --- UI1
    TM --- UI2
    DB --- TG
    MN --- OP

    %% Click Events
    click UI1 "https://github.com/jerrylususu/code2prompt/blob/main/index.html"
    click UI2 "https://github.com/jerrylususu/code2prompt/blob/main/styles.css"
    click GHP "https://github.com/jerrylususu/code2prompt/blob/main/js/githubHandler.js"
    click ZH "https://github.com/jerrylususu/code2prompt/blob/main/js/zipHandler.js"
    click FT "https://github.com/jerrylususu/code2prompt/blob/main/js/fileTree.js"
    click TG "https://github.com/jerrylususu/code2prompt/blob/main/js/textGenerator.js"
    click EH "https://github.com/jerrylususu/code2prompt/blob/main/js/editorHandler.js"
    click UT "https://github.com/jerrylususu/code2prompt/blob/main/js/utils.js"
    click UH "https://github.com/jerrylususu/code2prompt/blob/main/js/uiHelpers.js"
    click TM "https://github.com/jerrylususu/code2prompt/blob/main/js/theme.js"
    click DB "https://github.com/jerrylususu/code2prompt/blob/main/js/debug.js"
    click MN "https://github.com/jerrylususu/code2prompt/blob/main/js/main.js"

    %% Styles
    classDef ui fill:#a1c4fd,stroke:#1f6fb2,stroke-width:2px;
    classDef proc fill:#c7f9cc,stroke:#3f7d20,stroke-width:2px;
    classDef util fill:#ffe5b4,stroke:#ff8c00,stroke-width:2px;
    classDef ext fill:#d3d3d3,stroke:#696969,stroke-width:2px;
```
