# kelvinauta/contexo architecture

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

- Interactive diagram: https://gitdiagram.com/kelvinauta/contexo
- Repository: https://github.com/kelvinauta/contexo

## Overview

ConteXo is a CLI that scans a project, reads and transforms its files, then emits token-aware, configurable context to stdout. Its main workflow runs from CLI configuration through scanning, reading, processing, formatting, and output pagination; summary statistics and skipped-path reporting are additional output branches. The README documents filtering, ignore rules, comment/whitespace cleaning, truncation, line numbering, and model comparison. Some orchestration details and subsystem internals are unsampled, so uncertain links are omitted.

Main entry points: [`src/index.ts`](https://github.com/kelvinauta/contexo/blob/main/src/index.ts) (CLI workflow), [`src/core/measure.ts`](https://github.com/kelvinauta/contexo/blob/main/src/core/measure.ts) (Text metrics), [`src/core/scanner.ts`](https://github.com/kelvinauta/contexo/blob/main/src/core/scanner.ts) (Project scanner), [`src/core/processor.ts`](https://github.com/kelvinauta/contexo/blob/main/src/core/processor.ts) (Text processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and orchestration"]
  node_main["CLI workflow<br/>[index.ts]"]
  node_cli["Argument parsing<br/>[index.ts]"]
  node_defaults["Default config<br/>[defaults.ts]"]
end

subgraph group_files["Project discovery"]
  node_scanner["Project scanner<br/>[scanner.ts]"]
  node_reader["File reader<br/>[reader.ts]"]
end

subgraph group_transform["Content transformation"]
  node_processor["Text processor<br/>[processor.ts]"]
  node_cleaner["Comment cleaner"]
  node_truncate["Truncation<br/>[truncate.ts]"]
  node_formatter["Context formatter<br/>[formatter.ts]"]
end

subgraph group_output["Output and analysis"]
  node_measure["Text metrics<br/>[measure.ts]"]
  node_tokenizer["Token estimates<br/>[tokenizer.ts]"]
  node_modelcache[("Model cache<br/>[model-cache.ts]")]
  node_templates["Summary rendering"]
  node_document["Output document<br/>[document.ts]"]
  node_paginator["Output pagination<br/>[paginator.ts]"]
end

node_user(("CLI user"))
node_filesystem[("Project files")]
node_modelsdev["Models.dev data"]
node_stdout(("Standard output"))

node_user -->|"invokes"| node_main
node_main -->|"parses options"| node_cli
node_cli -->|"uses defaults"| node_defaults
node_main -->|"scans project"| node_scanner
node_scanner -->|"inspects entries"| node_filesystem
node_scanner -->|"provides file list"| node_reader
node_reader -->|"reads content"| node_filesystem
node_main -->|"reads files"| node_reader
node_main -->|"processes files"| node_processor
node_processor -->|"strips comments"| node_cleaner
node_processor -->|"truncates content"| node_truncate
node_main -->|"formats context"| node_formatter
node_main -->|"measures output"| node_measure
node_main -->|"estimates tokens"| node_tokenizer
node_tokenizer -->|"measures text"| node_measure
node_tokenizer -->|"loads model data"| node_modelcache
node_modelcache -.->|"uses cached model data"| node_modelsdev
node_main -->|"renders summaries"| node_templates
node_templates -->|"formats metrics"| node_measure
node_main -->|"assembles sections"| node_document
node_main -->|"paginates output"| node_paginator
node_paginator -->|"measures pages"| node_measure
node_main -->|"writes output"| node_stdout

click node_main "https://github.com/kelvinauta/contexo/blob/main/src/index.ts"
click node_cli "https://github.com/kelvinauta/contexo/blob/main/src/cli/index.ts"
click node_defaults "https://github.com/kelvinauta/contexo/blob/main/src/config/defaults.ts"
click node_scanner "https://github.com/kelvinauta/contexo/blob/main/src/core/scanner.ts"
click node_reader "https://github.com/kelvinauta/contexo/blob/main/src/core/reader.ts"
click node_processor "https://github.com/kelvinauta/contexo/blob/main/src/core/processor.ts"
click node_cleaner "https://github.com/kelvinauta/contexo/blob/main/src/core/cleaners/comment-stripper.ts"
click node_truncate "https://github.com/kelvinauta/contexo/blob/main/src/core/truncate.ts"
click node_formatter "https://github.com/kelvinauta/contexo/blob/main/src/core/formatter.ts"
click node_measure "https://github.com/kelvinauta/contexo/blob/main/src/core/measure.ts"
click node_tokenizer "https://github.com/kelvinauta/contexo/blob/main/src/core/tokenizer.ts"
click node_modelcache "https://github.com/kelvinauta/contexo/blob/main/src/core/model-cache.ts"
click node_templates "https://github.com/kelvinauta/contexo/blob/main/src/core/section-templates.ts"
click node_document "https://github.com/kelvinauta/contexo/blob/main/src/core/document.ts"
click node_paginator "https://github.com/kelvinauta/contexo/blob/main/src/core/paginator.ts"

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_main,node_cli,node_defaults,node_user toneBlue
class node_scanner,node_reader,node_filesystem toneAmber
class node_processor,node_cleaner,node_truncate,node_formatter toneMint
class node_measure,node_tokenizer,node_modelcache,node_templates,node_document,node_paginator toneRose
class node_modelsdev,node_stdout toneIndigo
```

## Components

### CLI and orchestration

- [CLI workflow](https://github.com/kelvinauta/contexo/blob/main/src/index.ts): `src/index.ts`
- [Argument parsing](https://github.com/kelvinauta/contexo/blob/main/src/cli/index.ts): `src/cli/index.ts`
- [Default config](https://github.com/kelvinauta/contexo/blob/main/src/config/defaults.ts): `src/config/defaults.ts`

### Project discovery

- [Project scanner](https://github.com/kelvinauta/contexo/blob/main/src/core/scanner.ts): `src/core/scanner.ts`
- [File reader](https://github.com/kelvinauta/contexo/blob/main/src/core/reader.ts): `src/core/reader.ts`

### Content transformation

- [Text processor](https://github.com/kelvinauta/contexo/blob/main/src/core/processor.ts): `src/core/processor.ts`
- [Comment cleaner](https://github.com/kelvinauta/contexo/blob/main/src/core/cleaners/comment-stripper.ts): `src/core/cleaners/comment-stripper.ts`
- [Truncation](https://github.com/kelvinauta/contexo/blob/main/src/core/truncate.ts): `src/core/truncate.ts`
- [Context formatter](https://github.com/kelvinauta/contexo/blob/main/src/core/formatter.ts): `src/core/formatter.ts`

### Output and analysis

- [Text metrics](https://github.com/kelvinauta/contexo/blob/main/src/core/measure.ts): `src/core/measure.ts`
- [Token estimates](https://github.com/kelvinauta/contexo/blob/main/src/core/tokenizer.ts): `src/core/tokenizer.ts`
- [Model cache](https://github.com/kelvinauta/contexo/blob/main/src/core/model-cache.ts): `src/core/model-cache.ts`
- [Summary rendering](https://github.com/kelvinauta/contexo/blob/main/src/core/section-templates.ts): `src/core/section-templates.ts`
- [Output document](https://github.com/kelvinauta/contexo/blob/main/src/core/document.ts): `src/core/document.ts`
- [Output pagination](https://github.com/kelvinauta/contexo/blob/main/src/core/paginator.ts): `src/core/paginator.ts`

### Other components

- **CLI user**
- **Project files**
- **Models.dev data**
- **Standard output**

## Connections

- CLI user → CLI workflow: invokes
- CLI workflow → Argument parsing: parses options
- Argument parsing → Default config: uses defaults
- CLI workflow → Project scanner: scans project
- Project scanner → Project files: inspects entries
- Project scanner → File reader: provides file list
- File reader → Project files: reads content
- CLI workflow → File reader: reads files
- CLI workflow → Text processor: processes files
- Text processor → Comment cleaner: strips comments
- Text processor → Truncation: truncates content
- CLI workflow → Context formatter: formats context
- CLI workflow → Text metrics: measures output
- CLI workflow → Token estimates: estimates tokens
- Token estimates → Text metrics: measures text
- Token estimates → Model cache: loads model data
- Model cache → Models.dev data: uses cached model data
- CLI workflow → Summary rendering: renders summaries
- Summary rendering → Text metrics: formats metrics
- CLI workflow → Output document: assembles sections
- CLI workflow → Output pagination: paginates output
- Output pagination → Text metrics: measures pages
- CLI workflow → Standard output: writes output