# hassanhassankerdash/codetxt architecture

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

- Interactive diagram: https://gitdiagram.com/hassanhassankerdash/codetxt
- Repository: https://github.com/hassanhassankerdash/codetxt

## Overview

##### Project type and purpose
- CodeTxt is a Node.js / TypeScript CLI tool that “ingests” any Git repository (remote or local), filters and formats its code, and emits a prompt-friendly text dump for LLMs or other downstream consumers.
- It is not a full-stack app or microservices system; it is a single, monolithic CLI pipeline with well-defined modular stages.

##### File structure
- Top-level:
- README.md, package.json, tsconfig.json – project metadata, build and runtime configuration.
- src/ – the entire CLI implementation.
- src breakdown:
- index.ts – CLI entry point; wires up the command, flags, and kicks off main logic.
- main.ts – orchestrates the overall pipeline.
- clone.ts – handles git clone or local dir resolution.
- ingestion.ts – walks the filesystem or cloned repo to read files.
- query-parser.ts – parses include/exclude glob patterns and other flags.
- output-formatter.ts – assembles and writes the final text output.
- types.ts – shared type definitions across modules.
- utils/ – helper modules:
– constants.ts (flag defaults, size limits)
– ignore-helper.ts (parsing .gitignore and include-gitignored logic)
– pattern-matcher.ts (glob matching engine)
– display.ts (console logging, progress display)
- No additional services (databases, HTTP servers, etc.).

##### Key README insights
- Describes CLI flags and behavior (branch, max-size, include/exclude patterns, output destination).
- Emphasizes pattern-based filtering as a core feature.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External systems
    subgraph "External Systems"
        GitRepo{{"GitHub/GitLab"}}:::external
        LocalFS[(Local File System)]:::external
        STDOUT(("STDOUT")):::external
    end

    %% Source code modules
    subgraph "src/"
        CLI["CLI Interface\nindex.ts"]:::core
        CmdParser["Command Parser\nquery-parser.ts\ntypes.ts"]:::core
        Orch["Orchestrator\nmain.ts"]:::core
        GitHandler["Git Handler\nclone.ts"]:::core
        Ing["File Ingestion Engine\ningestion.ts\nignore-helper.ts"]:::core
        PatternFilter["Pattern Filter\npattern-matcher.ts\nquery-parser.ts"]:::plugin
        Output["Output Formatter\noutput-formatter.ts\ndisplay.ts"]:::core
        Constants["Utilities\nconstants.ts"]:::util
    end

    %% Data flow
    User(("User")):::external -->|runs CLI| CLI
    CLI -->|"flags & args"| CmdParser
    CmdParser -->|"parsed options"| Orch

    Orch -->|"--repo URL"| GitHandler
    GitHandler -->|"git clone"| GitRepo
    GitHandler -->|"cloned code"| LocalFS
    Orch -->|"--local path"| LocalFS

    Orch -->|"start ingestion"| Ing
    Ing -->|"raw file streams"| PatternFilter
    PatternFilter -->|"filtered file streams"| Output
    Output -->|"formatted text"| STDOUT
    Output -->|"write to file"| LocalFS

    %% Utility dependencies
    CmdParser -.-> Constants
    Ing -.-> Constants
    PatternFilter -.-> Constants
    Output -.-> Constants

    %% Click Events
    click CLI "https://github.com/hassanhassankerdash/codetxt/blob/main/src/index.ts"
    click CmdParser "https://github.com/hassanhassankerdash/codetxt/blob/main/src/query-parser.ts"
    click CmdParser "https://github.com/hassanhassankerdash/codetxt/blob/main/src/types.ts"
    click Orch "https://github.com/hassanhassankerdash/codetxt/blob/main/src/main.ts"
    click GitHandler "https://github.com/hassanhassankerdash/codetxt/blob/main/src/clone.ts"
    click Ing "https://github.com/hassanhassankerdash/codetxt/blob/main/src/ingestion.ts"
    click Ing "https://github.com/hassanhassankerdash/codetxt/blob/main/src/utils/ignore-helper.ts"
    click PatternFilter "https://github.com/hassanhassankerdash/codetxt/blob/main/src/utils/pattern-matcher.ts"
    click PatternFilter "https://github.com/hassanhassankerdash/codetxt/blob/main/src/query-parser.ts"
    click Output "https://github.com/hassanhassankerdash/codetxt/blob/main/src/output-formatter.ts"
    click Output "https://github.com/hassanhassankerdash/codetxt/blob/main/src/utils/display.ts"
    click Constants "https://github.com/hassanhassankerdash/codetxt/blob/main/src/utils/constants.ts"

    %% Styles
    classDef core fill:#a3f7b5,stroke:#333,stroke-width:1px;
    classDef util fill:#fef08a,stroke:#333,stroke-width:1px,shape:hexagon;
    classDef external fill:#bae6fd,stroke:#333,stroke-width:1px;
    classDef plugin fill:#c7d2fe,stroke:#333,stroke-width:1px;
```
