# cyclotruc/gitingest architecture

> Architecture diagram of the GitHub repository cyclotruc/gitingest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cyclotruc/gitingest
- Repository: https://github.com/cyclotruc/gitingest

## Overview

Gitingest turns a repository URL or local directory into a prompt-ready digest with a file tree, content, and size/token statistics. Users can invoke it through the Python API or CLI, or submit repositories through the self-hosted web service; the service can cache and serve digest files through S3. The graph follows input parsing, repository access, file analysis, formatting, and web delivery. Several server and utility relationships are supported only by the SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`src/server/query_processor.py`](https://github.com/cyclotruc/gitingest/blob/main/src/server/query_processor.py) (Request processor), [`src/gitingest/entrypoint.py`](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/entrypoint.py) (Ingest entrypoint), [`src/server/main.py`](https://github.com/cyclotruc/gitingest/blob/main/src/server/main.py) (Web application), [`src/server/routers/ingest.py`](https://github.com/cyclotruc/gitingest/blob/main/src/server/routers/ingest.py) (Ingest routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion core"]
  node_entrypoint["Ingest entrypoint<br/>[entrypoint.py]"]
  node_query_parser["Query parser<br/>[query_parser.py]"]
  node_clone["Repository clone<br/>[clone.py]"]
  node_ingestion["File analysis<br/>[ingestion.py]"]
  node_filesystem["Filesystem model<br/>[filesystem.py]"]
  node_formatter["Digest formatter"]
  node_query_schema["Ingestion query<br/>[ingestion.py]"]
  node_clone_schema["Clone config<br/>[cloning.py]"]
end

subgraph group_support["Git and filtering"]
  node_git_utils["Git operations<br/>[git_utils.py]"]
  node_query_utils["Query helpers"]
  node_ignore_patterns["Ignore rules<br/>[ignore_patterns.py]"]
  node_pattern_utils["Pattern matching<br/>[pattern_utils.py]"]
  node_logging["Logging<br/>[logging_config.py]"]
end

subgraph group_web["Web service"]
  node_web_app["Web application<br/>[main.py]"]
  node_ingest_routes["Ingest routes<br/>[ingest.py]"]
  node_query_processor["Request processor<br/>[query_processor.py]"]
  node_request_models["Request models<br/>[models.py]"]
  node_web_config["Server configuration<br/>[server_config.py]"]
  node_web_helpers["Route helpers<br/>[routers_utils.py]"]
  node_index_routes["Landing routes<br/>[index.py]"]
  node_dynamic_routes["Dynamic routes<br/>[dynamic.py]"]
end

subgraph group_delivery["Digest delivery"]
  node_s3[("S3 storage<br/>[s3_utils.py]")]
  node_download["Digest download<br/>[ingest.py]"]
end

node_user(("User"))
node_cli["CLI<br/>[__main__.py]"]
node_python_api["Python API<br/>[__init__.py]"]
node_web_user(("Web user"))
node_browser["Browser interface<br/>[index.js]"]

node_user -->|"runs"| node_cli
node_user -->|"calls"| node_python_api
node_cli -->|"invokes"| node_entrypoint
node_python_api -.->|"exposes"| node_entrypoint
node_entrypoint -->|"parses input"| node_query_parser
node_entrypoint -->|"clones repository"| node_clone
node_entrypoint -->|"processes files"| node_ingestion
node_entrypoint -->|"loads rules"| node_ignore_patterns
node_entrypoint -->|"applies patterns"| node_pattern_utils
node_query_parser -->|"uses helpers"| node_query_utils
node_query_utils -->|"resolves refs"| node_git_utils
node_query_parser -->|"creates query"| node_query_schema
node_query_schema -->|"builds config"| node_clone_schema
node_clone -->|"uses config"| node_clone_schema
node_clone -->|"uses Git"| node_git_utils
node_ingestion -->|"builds tree"| node_filesystem
node_ingestion -->|"formats output"| node_formatter
node_pattern_utils -->|"uses rules"| node_ignore_patterns
node_web_user -.->|"submits repository"| node_browser
node_web_app -->|"registers routes"| node_ingest_routes
node_web_app -->|"registers routes"| node_index_routes
node_web_app -->|"registers routes"| node_dynamic_routes
node_ingest_routes -->|"delegates request"| node_web_helpers
node_web_helpers -->|"processes ingest"| node_query_processor
node_ingest_routes -->|"validates request"| node_request_models
node_query_processor -->|"parses repository"| node_query_parser
node_query_processor -->|"clones repository"| node_clone
node_query_processor -->|"analyzes files"| node_ingestion
node_query_processor -->|"filters files"| node_pattern_utils
node_query_processor -->|"checks and stores"| node_s3
node_ingest_routes -->|"serves digest"| node_download
node_web_app -->|"loads settings"| node_web_config
node_query_processor -->|"logs activity"| node_logging

click node_cli "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/__main__.py"
click node_python_api "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/__init__.py"
click node_entrypoint "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/entrypoint.py"
click node_query_parser "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/query_parser.py"
click node_clone "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/clone.py"
click node_ingestion "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/ingestion.py"
click node_filesystem "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/schemas/filesystem.py"
click node_formatter "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/output_formatter.py"
click node_query_schema "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/schemas/ingestion.py"
click node_clone_schema "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/schemas/cloning.py"
click node_git_utils "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/utils/git_utils.py"
click node_query_utils "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/utils/query_parser_utils.py"
click node_ignore_patterns "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/utils/ignore_patterns.py"
click node_pattern_utils "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/utils/pattern_utils.py"
click node_logging "https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/utils/logging_config.py"
click node_web_app "https://github.com/cyclotruc/gitingest/blob/main/src/server/main.py"
click node_ingest_routes "https://github.com/cyclotruc/gitingest/blob/main/src/server/routers/ingest.py"
click node_query_processor "https://github.com/cyclotruc/gitingest/blob/main/src/server/query_processor.py"
click node_request_models "https://github.com/cyclotruc/gitingest/blob/main/src/server/models.py"
click node_web_config "https://github.com/cyclotruc/gitingest/blob/main/src/server/server_config.py"
click node_web_helpers "https://github.com/cyclotruc/gitingest/blob/main/src/server/routers_utils.py"
click node_s3 "https://github.com/cyclotruc/gitingest/blob/main/src/server/s3_utils.py"
click node_download "https://github.com/cyclotruc/gitingest/blob/main/src/server/routers/ingest.py"
click node_index_routes "https://github.com/cyclotruc/gitingest/blob/main/src/server/routers/index.py"
click node_dynamic_routes "https://github.com/cyclotruc/gitingest/blob/main/src/server/routers/dynamic.py"
click node_browser "https://github.com/cyclotruc/gitingest/blob/main/src/static/js/index.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entrypoint,node_query_parser,node_clone,node_ingestion,node_filesystem,node_formatter,node_query_schema,node_clone_schema,node_user,node_web_user,node_browser toneBlue
class node_git_utils,node_query_utils,node_ignore_patterns,node_pattern_utils,node_logging toneAmber
class node_web_app,node_ingest_routes,node_query_processor,node_request_models,node_web_config,node_web_helpers,node_index_routes,node_dynamic_routes,node_python_api toneMint
class node_s3,node_download toneRose
class node_cli toneTeal
```

## Components

### Ingestion core

- [Ingest entrypoint](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/entrypoint.py): `src/gitingest/entrypoint.py`
- [Query parser](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/query_parser.py): `src/gitingest/query_parser.py`
- [Repository clone](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/clone.py): `src/gitingest/clone.py`
- [File analysis](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/ingestion.py): `src/gitingest/ingestion.py`
- [Filesystem model](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/schemas/filesystem.py): `src/gitingest/schemas/filesystem.py`
- [Digest formatter](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/output_formatter.py): `src/gitingest/output_formatter.py`
- [Ingestion query](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/schemas/ingestion.py): `src/gitingest/schemas/ingestion.py`
- [Clone config](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/schemas/cloning.py): `src/gitingest/schemas/cloning.py`

### Git and filtering

- [Git operations](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/utils/git_utils.py): `src/gitingest/utils/git_utils.py`
- [Query helpers](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/utils/query_parser_utils.py): `src/gitingest/utils/query_parser_utils.py`
- [Ignore rules](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/utils/ignore_patterns.py): `src/gitingest/utils/ignore_patterns.py`
- [Pattern matching](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/utils/pattern_utils.py): `src/gitingest/utils/pattern_utils.py`
- [Logging](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/utils/logging_config.py): `src/gitingest/utils/logging_config.py`

### Web service

- [Web application](https://github.com/cyclotruc/gitingest/blob/main/src/server/main.py): `src/server/main.py`
- [Ingest routes](https://github.com/cyclotruc/gitingest/blob/main/src/server/routers/ingest.py): `src/server/routers/ingest.py`
- [Request processor](https://github.com/cyclotruc/gitingest/blob/main/src/server/query_processor.py): `src/server/query_processor.py`
- [Request models](https://github.com/cyclotruc/gitingest/blob/main/src/server/models.py): `src/server/models.py`
- [Server configuration](https://github.com/cyclotruc/gitingest/blob/main/src/server/server_config.py): `src/server/server_config.py`
- [Route helpers](https://github.com/cyclotruc/gitingest/blob/main/src/server/routers_utils.py): `src/server/routers_utils.py`
- [Landing routes](https://github.com/cyclotruc/gitingest/blob/main/src/server/routers/index.py): `src/server/routers/index.py`
- [Dynamic routes](https://github.com/cyclotruc/gitingest/blob/main/src/server/routers/dynamic.py): `src/server/routers/dynamic.py`

### Digest delivery

- [S3 storage](https://github.com/cyclotruc/gitingest/blob/main/src/server/s3_utils.py): `src/server/s3_utils.py`
- [Digest download](https://github.com/cyclotruc/gitingest/blob/main/src/server/routers/ingest.py): `src/server/routers/ingest.py`

### Other components

- **User**
- [CLI](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/__main__.py): `src/gitingest/__main__.py`
- [Python API](https://github.com/cyclotruc/gitingest/blob/main/src/gitingest/__init__.py): `src/gitingest/__init__.py`
- **Web user**
- [Browser interface](https://github.com/cyclotruc/gitingest/blob/main/src/static/js/index.js): `src/static/js/index.js`

## Connections

- User → CLI: runs (evidence: `README.md`)
- User → Python API: calls (evidence: `README.md`)
- CLI → Ingest entrypoint: invokes
- Python API → Ingest entrypoint: exposes
- Ingest entrypoint → Query parser: parses input (evidence: `src/gitingest/entrypoint.py`)
- Ingest entrypoint → Repository clone: clones repository (evidence: `src/gitingest/entrypoint.py`)
- Ingest entrypoint → File analysis: processes files (evidence: `src/gitingest/entrypoint.py`)
- Ingest entrypoint → Ignore rules: loads rules (evidence: `src/gitingest/entrypoint.py`)
- Ingest entrypoint → Pattern matching: applies patterns (evidence: `src/gitingest/entrypoint.py`)
- Query parser → Query helpers: uses helpers (evidence: `src/gitingest/query_parser.py`)
- Query helpers → Git operations: resolves refs (evidence: `src/gitingest/utils/query_parser_utils.py`)
- Query parser → Ingestion query: creates query (evidence: `src/gitingest/query_parser.py`)
- Ingestion query → Clone config: builds config (evidence: `src/gitingest/schemas/ingestion.py`)
- Repository clone → Clone config: uses config (evidence: `src/gitingest/clone.py`)
- Repository clone → Git operations: uses Git (evidence: `src/gitingest/clone.py`)
- File analysis → Filesystem model: builds tree (evidence: `src/gitingest/ingestion.py`)
- File analysis → Digest formatter: formats output (evidence: `src/gitingest/ingestion.py`)
- Pattern matching → Ignore rules: uses rules (evidence: `src/gitingest/utils/pattern_utils.py`)
- Web user → Browser interface: submits repository
- Web application → Ingest routes: registers routes (evidence: `src/server/main.py`)
- Web application → Landing routes: registers routes (evidence: `src/server/main.py`)
- Web application → Dynamic routes: registers routes (evidence: `src/server/main.py`)
- Ingest routes → Route helpers: delegates request (evidence: `src/server/routers/ingest.py`)
- Route helpers → Request processor: processes ingest (evidence: `src/server/routers_utils.py`)
- Ingest routes → Request models: validates request (evidence: `src/server/routers/ingest.py`)
- Request processor → Query parser: parses repository (evidence: `src/server/query_processor.py`)
- Request processor → Repository clone: clones repository (evidence: `src/server/query_processor.py`)
- Request processor → File analysis: analyzes files (evidence: `src/server/query_processor.py`)
- Request processor → Pattern matching: filters files (evidence: `src/server/query_processor.py`)
- Request processor → S3 storage: checks and stores (evidence: `src/server/query_processor.py`)
- Ingest routes → Digest download: serves digest (evidence: `src/server/routers/ingest.py`)
- Web application → Server configuration: loads settings (evidence: `src/server/main.py`)
- Request processor → Logging: logs activity (evidence: `src/server/query_processor.py`)
