# alokrajiv/astrolark architecture

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

- Interactive diagram: https://gitdiagram.com/alokrajiv/astrolark
- Repository: https://github.com/alokrajiv/astrolark

## Overview

1. **What this repo is**
   Astrolark is a **TypeScript Node.js CLI** for turning a project directory into an AI-friendly snapshot. Its main job is to walk a codebase, collect structure and file contents, and emit a consolidated overview in a format that can be pasted into an LLM or saved to disk.

2. **Top-level command boundary**
   The entrypoint in `src/index.ts` likely wires up the CLI commands and dispatches into the two main user flows: **`read`** for generating an overview and **`edit`** for the editor pipeline. This is the primary boundary between user input and the internal processing code.

3. **Interactive vs non-interactive configuration**
   `src/wizard.ts` implements the interactive setup path described in the README. The CLI can also run headless with flags like `--base-path`, `--filter`, `--output`, and `--no-wizard`, so configuration is split between a prompt-driven mode and direct argument parsing.

4. **Project scanning and file selection**
   `src/fileUtils.ts` is the file-system boundary for discovering candidates, respecting `.gitignore`, excluding binary files, and applying include filters. This subsystem determines the exact scope of the snapshot before any formatting happens.

5. **Overview generation pipeline**
   `src/overviewGenerator.ts` is the core “read” engine. It takes the selected files and project structure and produces the final overview content. This is the central transformation step from repository state to serialized summary.

6. **Output formatting and delivery**
   The generator supports at least **YAML and XML** output formats, so there is a serialization layer that sits after scanning. The README also calls out clipboard copying and saving to a file, which means the final output has two sinks: local filesystem and clipboard integration.

7. **Shared domain constants**
   `src/constants.ts` likely holds format names, defaults, and command-level constants used across the CLI and generator. This keeps user-facing options and internal defaults consistent across the command flow.

8. **Separate editor subsystem**
   The `src/editor` directory is a distinct subsystem from the overview generator. It has its own entry module, parser, and multi-phase processor, indicating a staged transformation pipeline for a custom editor-oriented input format rather than the project scanning flow.

9. **Parser and staged processing**
   `src/editor/parser.ts` converts editor input into an intermediate representation. The `src/editor/processor` package then runs that representation through **four phases** (`phase1.ts` through `phase4.ts`), with shared types in `types.ts`. This strongly suggests incremental normalization/validation/transformation rather than a single-pass edit operation.

10. **Testing strategy and fixtures**
   The repository uses **Jest** (`jest.config.mjs`) and has targeted tests for the parser and the first three processor phases. The `tests/editor/scenes/heartbleed` fixture set, including `.alk`, source, and staged JSON files, shows the editor pipeline is validated with realistic multi-stage scenarios.

11. **Architectural split**
   At a high level, the repo is divided into two domains:
   - **Snapshot generation**: scan a project and serialize its contents for AI consumption.
   - **Editor processing**: parse a custom editor input and evolve it through staged processing.
   These domains share the same CLI/runtime but appear to be intentionally separated in the source tree.

12. **Runtime and tooling**
   The project is a **Node.js + TypeScript** codebase with a lockfile and Jest-based tests. There’s no sign of a server, database, or external API dependency; the key integrations are local filesystem access, Git ignore rules, and clipboard/output handling.

Main entry points: [`src/editor/processor/index.ts`](https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/index.ts) (Processor entry), [`src/index.ts`](https://github.com/alokrajiv/astrolark/blob/main/src/index.ts) (CLI entry), [`src/editor/processor/types.ts`](https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/types.ts) (Editor types), [`src/overviewGenerator.ts`](https://github.com/alokrajiv/astrolark/blob/main/src/overviewGenerator.ts) (Overview gen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI snapshot flow"]
  node_src_index["CLI entry<br/>command router<br/>[index.ts]"]
  node_src_wizard["Wizard<br/>interactive setup<br/>[wizard.ts]"]
  node_src_constants["Constants<br/>shared config<br/>[constants.ts]"]
  node_src_fileutils["File utils<br/>filesystem scan<br/>[fileUtils.ts]"]
  node_src_overview["Overview gen<br/>snapshot engine"]
end

subgraph group_editor["Editor pipeline"]
  node_src_editor_index["Editor entry<br/>[index.ts]"]
  node_src_editor_parser["Parser<br/>[parser.ts]"]
  node_src_editor_proc_index["Processor entry<br/>pipeline entry<br/>[index.ts]"]
  node_src_editor_phase1["Phase 1<br/>transform stage<br/>[phase1.ts]"]
  node_src_editor_phase2["Phase 2<br/>transform stage<br/>[phase2.ts]"]
  node_src_editor_phase3["Phase 3<br/>transform stage<br/>[phase3.ts]"]
  node_src_editor_phase4["Phase 4<br/>transform stage<br/>[phase4.ts]"]
  node_src_editor_types["Editor types<br/>shared model<br/>[types.ts]"]
end

subgraph group_tests["Test suite"]
  node_tests_parser["Parser test<br/>unit test<br/>[parser.test.ts]"]
  node_tests_p1["Phase 1 test<br/>unit test<br/>[phase1.test.ts]"]
  node_tests_p2["Phase 2 test<br/>unit test<br/>[phase2.test.ts]"]
  node_tests_p3["Phase 3 test<br/>unit test<br/>[phase3.test.ts]"]
  node_tests_scene["Heartbleed scene<br/>integration fixture<br/>[heartbleed.test.ts]"]
  node_tests_setup["Test setup<br/>test bootstrap<br/>[setup.ts]"]
end

node_src_index -->|"configures"| node_src_wizard
node_src_index -->|"scans"| node_src_fileutils
node_src_index -->|"reads"| node_src_overview
node_src_index -->|"routes"| node_src_editor_index
node_src_index -.->|"uses"| node_src_constants
node_src_wizard -.->|"reads"| node_src_constants
node_src_fileutils -->|"feeds"| node_src_overview
node_src_overview -.->|"formats"| node_src_constants
node_src_overview -.->|"depends on"| node_src_fileutils
node_src_editor_index -->|"parses"| node_src_editor_parser
node_src_editor_index -->|"processes"| node_src_editor_proc_index
node_src_editor_proc_index -->|"runs"| node_src_editor_phase1
node_src_editor_proc_index -->|"runs"| node_src_editor_phase2
node_src_editor_proc_index -->|"runs"| node_src_editor_phase3
node_src_editor_proc_index -->|"runs"| node_src_editor_phase4
node_src_editor_proc_index -.->|"shares types"| node_src_editor_types
node_src_editor_phase1 -.->|"uses"| node_src_editor_types
node_src_editor_phase2 -.->|"uses"| node_src_editor_types
node_src_editor_phase3 -.->|"uses"| node_src_editor_types
node_src_editor_phase4 -.->|"uses"| node_src_editor_types
node_tests_parser -->|"verifies"| node_src_editor_parser
node_tests_p1 -->|"verifies"| node_src_editor_phase1
node_tests_p2 -->|"verifies"| node_src_editor_phase2
node_tests_p3 -->|"verifies"| node_src_editor_phase3
node_tests_scene -->|"exercises"| node_src_editor_parser
node_tests_scene -->|"exercises"| node_src_editor_proc_index
node_tests_setup -.->|"supports"| node_tests_parser

click node_src_index "https://github.com/alokrajiv/astrolark/blob/main/src/index.ts"
click node_src_wizard "https://github.com/alokrajiv/astrolark/blob/main/src/wizard.ts"
click node_src_constants "https://github.com/alokrajiv/astrolark/blob/main/src/constants.ts"
click node_src_fileutils "https://github.com/alokrajiv/astrolark/blob/main/src/fileUtils.ts"
click node_src_overview "https://github.com/alokrajiv/astrolark/blob/main/src/overviewGenerator.ts"
click node_src_editor_index "https://github.com/alokrajiv/astrolark/blob/main/src/editor/index.ts"
click node_src_editor_parser "https://github.com/alokrajiv/astrolark/blob/main/src/editor/parser.ts"
click node_src_editor_proc_index "https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/index.ts"
click node_src_editor_phase1 "https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/phase1.ts"
click node_src_editor_phase2 "https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/phase2.ts"
click node_src_editor_phase3 "https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/phase3.ts"
click node_src_editor_phase4 "https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/phase4.ts"
click node_src_editor_types "https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/types.ts"
click node_tests_parser "https://github.com/alokrajiv/astrolark/blob/main/tests/editor/parser.test.ts"
click node_tests_p1 "https://github.com/alokrajiv/astrolark/blob/main/tests/editor/processor/phase1.test.ts"
click node_tests_p2 "https://github.com/alokrajiv/astrolark/blob/main/tests/editor/processor/phase2.test.ts"
click node_tests_p3 "https://github.com/alokrajiv/astrolark/blob/main/tests/editor/processor/phase3.test.ts"
click node_tests_scene "https://github.com/alokrajiv/astrolark/blob/main/tests/editor/scenes/heartbleed/heartbleed.test.ts"
click node_tests_setup "https://github.com/alokrajiv/astrolark/blob/main/tests/setup.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_src_index,node_src_wizard,node_src_constants,node_src_fileutils,node_src_overview toneBlue
class node_src_editor_index,node_src_editor_parser,node_src_editor_proc_index,node_src_editor_phase1,node_src_editor_phase2,node_src_editor_phase3,node_src_editor_phase4,node_src_editor_types toneAmber
class node_tests_parser,node_tests_p1,node_tests_p2,node_tests_p3,node_tests_scene,node_tests_setup toneMint
```

## Components

### CLI snapshot flow

Top-level command handling, configuration, scanning, and overview generation.

- [CLI entry](https://github.com/alokrajiv/astrolark/blob/main/src/index.ts): command router · Main CLI boundary that dispatches user commands and wires runtime options. · `src/index.ts`
- [Wizard](https://github.com/alokrajiv/astrolark/blob/main/src/wizard.ts): interactive setup · Prompt-driven configuration path for interactive CLI usage. · `src/wizard.ts`
- [Constants](https://github.com/alokrajiv/astrolark/blob/main/src/constants.ts): shared config · Command names, defaults, and shared user-facing constants. · `src/constants.ts`
- [File utils](https://github.com/alokrajiv/astrolark/blob/main/src/fileUtils.ts): filesystem scan · Discovers files, applies ignore rules, and filters binary or excluded content. · `src/fileUtils.ts`
- [Overview gen](https://github.com/alokrajiv/astrolark/blob/main/src/overviewGenerator.ts): snapshot engine · Core read pipeline that turns selected project files into an AI-friendly overview. · `src/overviewGenerator.ts`

### Editor pipeline

Parser and staged processor for the custom editor format.

- [Editor entry](https://github.com/alokrajiv/astrolark/blob/main/src/editor/index.ts): editor entry · Entry point for the editor subsystem and its internal pipeline. · `src/editor/index.ts`
- [Parser](https://github.com/alokrajiv/astrolark/blob/main/src/editor/parser.ts): input parser · Parses editor input into an intermediate representation. · `src/editor/parser.ts`
- [Processor entry](https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/index.ts): pipeline entry · Coordinates the staged editor processing pipeline. · `src/editor/processor/index.ts`
- [Phase 1](https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/phase1.ts): transform stage · First processing stage for normalization or validation. · `src/editor/processor/phase1.ts`
- [Phase 2](https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/phase2.ts): transform stage · Second processing stage in the editor pipeline. · `src/editor/processor/phase2.ts`
- [Phase 3](https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/phase3.ts): transform stage · Third processing stage in the editor pipeline. · `src/editor/processor/phase3.ts`
- [Phase 4](https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/phase4.ts): transform stage · Final processing stage in the editor pipeline. · `src/editor/processor/phase4.ts`
- [Editor types](https://github.com/alokrajiv/astrolark/blob/main/src/editor/processor/types.ts): shared model · Shared types and data structures used by the processor stages. · `src/editor/processor/types.ts`

### Test suite

Jest-based coverage for the editor pipeline and fixtures.

- [Parser test](https://github.com/alokrajiv/astrolark/blob/main/tests/editor/parser.test.ts): unit test · Verifies parser behavior for editor input. · `tests/editor/parser.test.ts`
- [Phase 1 test](https://github.com/alokrajiv/astrolark/blob/main/tests/editor/processor/phase1.test.ts): unit test · Covers the first processor stage. · `tests/editor/processor/phase1.test.ts`
- [Phase 2 test](https://github.com/alokrajiv/astrolark/blob/main/tests/editor/processor/phase2.test.ts): unit test · Covers the second processor stage. · `tests/editor/processor/phase2.test.ts`
- [Phase 3 test](https://github.com/alokrajiv/astrolark/blob/main/tests/editor/processor/phase3.test.ts): unit test · Covers the third processor stage. · `tests/editor/processor/phase3.test.ts`
- [Heartbleed scene](https://github.com/alokrajiv/astrolark/blob/main/tests/editor/scenes/heartbleed/heartbleed.test.ts): integration fixture · End-to-end editor scenario with source, staged JSON, and edits fixture data. · `tests/editor/scenes/heartbleed/heartbleed.test.ts`
- [Test setup](https://github.com/alokrajiv/astrolark/blob/main/tests/setup.ts): test bootstrap · Shared Jest setup for the test environment. · `tests/setup.ts`

## Connections

- CLI entry → Wizard: configures · Interactive mode is initialized from the CLI boundary.
- CLI entry → File utils: scans · CLI read flow delegates file discovery and filtering.
- CLI entry → Overview gen: reads · Dispatches the snapshot generation command into the overview engine.
- CLI entry → Editor entry: routes · CLI also exposes the editor subsystem as a separate command path.
- CLI entry → Constants: uses · Shares command names and defaults across the entrypoint and flows.
- Wizard → Constants: reads · Wizard prompts are driven by shared defaults and option names.
- File utils → Overview gen: feeds · Selected files and project structure are passed into overview generation.
- Overview gen → Constants: formats · Uses shared output mode and default configuration values.
- Overview gen → File utils: depends on · Overview generation relies on the file-selection boundary.
- Editor entry → Parser: parses · Editor entry starts by converting raw input into an intermediate form.
- Editor entry → Processor entry: processes · Parsed editor data is handed to the staged processor.
- Processor entry → Phase 1: runs · Processor begins with the first transformation stage.
- Processor entry → Phase 2: runs · Processor continues through the second transformation stage.
- Processor entry → Phase 3: runs · Processor continues through the third transformation stage.
- Processor entry → Phase 4: runs · Processor completes with the final transformation stage.
- Processor entry → Editor types: shares types · Pipeline stages use common editor data models.
- Phase 1 → Editor types: uses · Stage 1 operates on shared processor types.
- Phase 2 → Editor types: uses · Stage 2 operates on shared processor types.
- Phase 3 → Editor types: uses · Stage 3 operates on shared processor types.
- Phase 4 → Editor types: uses · Stage 4 operates on shared processor types.
- Parser test → Parser: verifies · Directly exercises parser behavior.
- Phase 1 test → Phase 1: verifies · Validates the first processing phase.
- Phase 2 test → Phase 2: verifies · Validates the second processing phase.
- Phase 3 test → Phase 3: verifies · Validates the third processing phase.
- Heartbleed scene → Parser: exercises · Integration fixture drives the editor parser and downstream flow.
- Heartbleed scene → Processor entry: exercises · Scenario validates staged processing end to end.
- Test setup → Parser test: supports · Shared test bootstrap underpins the Jest suite.