# bres777/stock-ledger-sim architecture

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

- Interactive diagram: https://gitdiagram.com/bres777/stock-ledger-sim
- Repository: https://github.com/bres777/stock-ledger-sim

## Overview

stock-ledger is a small Node.js command-line inventory ledger. A user invokes a command through the executable; the CLI dispatches movements, item settings, reports, or CSV import. Movements are appended to a JSONL ledger and settings to a separate JSONL file. CSV import parses and validates rows, then submits eligible movements to the ledger; reports combine ledger quantities with item settings. The graph follows documented commands and sampled call sites; unsampled implementation details are omitted.

Main entry points: [`src/cli.js`](https://github.com/bres777/stock-ledger-sim/blob/main/src/cli.js) (Command dispatcher), [`src/import.js`](https://github.com/bres777/stock-ledger-sim/blob/main/src/import.js) (Import processor), [`src/items.js`](https://github.com/bres777/stock-ledger-sim/blob/main/src/items.js) (Item settings), [`src/ledger.js`](https://github.com/bres777/stock-ledger-sim/blob/main/src/ledger.js) (Movement ledger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry"]
  node_executable["CLI executable<br/>[stock-ledger.js]"]
  node_cli["Command dispatcher<br/>[cli.js]"]
end

subgraph group_inventory["Inventory records"]
  node_ledger["Movement ledger<br/>[ledger.js]"]
  node_movement_file[("Movement JSONL<br/>[ledger.js]")]
  node_items["Item settings<br/>[items.js]"]
  node_settings_file[("Settings JSONL<br/>[items.js]")]
end

subgraph group_import["CSV import"]
  node_csv_input["CSV file"]
  node_csv_parser["CSV parser<br/>[csv.js]"]
  node_importer["Import processor<br/>[import.js]"]
  node_rejects_file["Rejects CSV"]
end

subgraph group_reporting["Reports"]
  node_reports["Stock reports<br/>[reports.js]"]
end

node_user(("User"))

node_user -->|"runs command"| node_executable
node_executable -->|"calls run"| node_cli
node_cli -->|"records and reads"| node_ledger
node_ledger -->|"reads and appends"| node_movement_file
node_cli -->|"sets and reads"| node_items
node_items -->|"uses lock and validation"| node_ledger
node_items -->|"reads and appends"| node_settings_file
node_cli -->|"requests report"| node_reports
node_reports -->|"uses price helpers"| node_items
node_cli -->|"starts import"| node_importer
node_cli -->|"passes file path"| node_csv_input
node_importer -->|"reads file"| node_csv_input
node_importer -->|"parses text"| node_csv_parser
node_importer -->|"records movements"| node_ledger
node_importer -->|"writes rejected rows"| node_rejects_file
node_cli -->|"passes quantities and settings"| node_reports

click node_executable "https://github.com/bres777/stock-ledger-sim/blob/main/bin/stock-ledger.js"
click node_cli "https://github.com/bres777/stock-ledger-sim/blob/main/src/cli.js"
click node_ledger "https://github.com/bres777/stock-ledger-sim/blob/main/src/ledger.js"
click node_movement_file "https://github.com/bres777/stock-ledger-sim/blob/main/src/ledger.js"
click node_items "https://github.com/bres777/stock-ledger-sim/blob/main/src/items.js"
click node_settings_file "https://github.com/bres777/stock-ledger-sim/blob/main/src/items.js"
click node_csv_parser "https://github.com/bres777/stock-ledger-sim/blob/main/src/csv.js"
click node_importer "https://github.com/bres777/stock-ledger-sim/blob/main/src/import.js"
click node_reports "https://github.com/bres777/stock-ledger-sim/blob/main/src/reports.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_executable,node_cli,node_user toneBlue
class node_ledger,node_movement_file,node_items,node_settings_file toneAmber
class node_csv_input,node_csv_parser,node_importer,node_rejects_file toneMint
class node_reports toneRose
```

## Components

### Command entry

- [CLI executable](https://github.com/bres777/stock-ledger-sim/blob/main/bin/stock-ledger.js): `bin/stock-ledger.js`
- [Command dispatcher](https://github.com/bres777/stock-ledger-sim/blob/main/src/cli.js): `src/cli.js`

### Inventory records

- [Movement ledger](https://github.com/bres777/stock-ledger-sim/blob/main/src/ledger.js): `src/ledger.js`
- [Movement JSONL](https://github.com/bres777/stock-ledger-sim/blob/main/src/ledger.js): `src/ledger.js`
- [Item settings](https://github.com/bres777/stock-ledger-sim/blob/main/src/items.js): `src/items.js`
- [Settings JSONL](https://github.com/bres777/stock-ledger-sim/blob/main/src/items.js): `src/items.js`

### CSV import

- **CSV file**
- [CSV parser](https://github.com/bres777/stock-ledger-sim/blob/main/src/csv.js): `src/csv.js`
- [Import processor](https://github.com/bres777/stock-ledger-sim/blob/main/src/import.js): `src/import.js`
- **Rejects CSV**

### Reports

- [Stock reports](https://github.com/bres777/stock-ledger-sim/blob/main/src/reports.js): `src/reports.js`

### Other components

- **User**

## Connections

- User → CLI executable: runs command (evidence: `README.md`)
- CLI executable → Command dispatcher: calls run (evidence: `bin/stock-ledger.js`)
- Command dispatcher → Movement ledger: records and reads (evidence: `src/cli.js`)
- Movement ledger → Movement JSONL: reads and appends (evidence: `src/ledger.js`)
- Command dispatcher → Item settings: sets and reads (evidence: `src/cli.js`)
- Item settings → Movement ledger: uses lock and validation (evidence: `src/items.js`)
- Item settings → Settings JSONL: reads and appends (evidence: `src/items.js`)
- Command dispatcher → Stock reports: requests report (evidence: `src/cli.js`)
- Stock reports → Item settings: uses price helpers (evidence: `src/reports.js`)
- Command dispatcher → Import processor: starts import (evidence: `src/cli.js`)
- Command dispatcher → CSV file: passes file path (evidence: `src/cli.js`)
- Import processor → CSV file: reads file (evidence: `src/import.js`)
- Import processor → CSV parser: parses text (evidence: `src/import.js`)
- Import processor → Movement ledger: records movements (evidence: `src/import.js`)
- Import processor → Rejects CSV: writes rejected rows (evidence: `README.md`)
- Command dispatcher → Stock reports: passes quantities and settings (evidence: `src/cli.js`)
