# voidcosmos/npkill architecture

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

- Interactive diagram: https://gitdiagram.com/voidcosmos/npkill
- Repository: https://github.com/voidcosmos/npkill

## Overview

npkill is an interactive cleanup CLI: it discovers target directories, enriches and displays results, then lets the user remove selected folders. It also supports profile/configuration selection, risk-aware filtering, and JSON output. The graph follows the documented workflow and sampled calls; several backend and UI details are unsampled, so uncertain internal links are omitted.

Main entry points: [`src/cli/cli.controller.ts`](https://github.com/voidcosmos/npkill/blob/main/src/cli/cli.controller.ts) (Command controller), [`src/main.ts`](https://github.com/voidcosmos/npkill/blob/main/src/main.ts) (CLI entry), [`src/cli/services/scan.service.ts`](https://github.com/voidcosmos/npkill/blob/main/src/cli/services/scan.service.ts) (Scan service), [`src/core/npkill.ts`](https://github.com/voidcosmos/npkill/blob/main/src/core/npkill.ts) (Scan engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["CLI startup"]
  node_entry["CLI entry<br/>[main.ts]"]
  node_controller["Command controller<br/>[cli.controller.ts]"]
  node_console["Argument parser<br/>[console.service.ts]"]
end

subgraph group_scan["Discovery and analysis"]
  node_scanner["Scan service<br/>[scan.service.ts]"]
  node_engine["Scan engine<br/>[npkill.ts]"]
  node_worker_manager["Worker manager"]
  node_worker["File worker<br/>[files.worker.ts]"]
  node_logger["Logger<br/>[logger.service.ts]"]
end

subgraph group_interaction["Interactive experience"]
  node_ui_service["UI coordinator<br/>[ui.service.ts]"]
  node_results_ui["Results panel<br/>[results.ui.ts]"]
  node_header_ui["Header and stats<br/>[stats.ui.ts]"]
  node_help_ui["Help panel<br/>[help.ui.ts]"]
  node_details_ui["Result details"]
end

subgraph group_output["Results and output"]
  node_results["Result tracking<br/>[results.service.ts]"]
  node_json["JSON output"]
end

subgraph group_settings["Configuration"]
  node_config["Config loader<br/>[config.service.ts]"]
  node_profiles["Profile service"]
end

node_user(("CLI user"))
node_filesystem["Local filesystem"]
node_terminal["Terminal"]

node_user -->|"runs command"| node_entry
node_entry -->|"starts"| node_controller
node_entry -->|"creates"| node_logger
node_entry -->|"creates"| node_results
node_entry -->|"creates"| node_config
node_entry -->|"creates"| node_profiles
node_entry -->|"creates"| node_scanner
node_entry -->|"creates"| node_json
node_entry -->|"creates"| node_console
node_entry -->|"creates"| node_ui_service
node_controller -->|"requests scan"| node_scanner
node_scanner -->|"starts scan"| node_engine
node_scanner -->|"gets size and age"| node_engine
node_controller -->|"tracks results"| node_results
node_controller -->|"processes scan output"| node_json
node_controller -->|"renders interface"| node_ui_service
node_controller -->|"registers panel"| node_results_ui
node_controller -->|"opens details"| node_details_ui
node_controller -->|"shows help"| node_help_ui
node_controller -->|"registers stats"| node_header_ui
node_results_ui -->|"reads results"| node_results
node_controller -->|"deletes folder"| node_engine
node_worker_manager -->|"dispatches jobs"| node_worker
node_worker_manager -->|"logs errors"| node_logger
node_engine -.->|"scans and deletes"| node_filesystem
node_controller -.->|"uses settings"| node_config
node_controller -.->|"selects profiles"| node_profiles
node_json -.->|"writes output"| node_terminal
node_ui_service -.->|"draws interface"| node_terminal

click node_entry "https://github.com/voidcosmos/npkill/blob/main/src/main.ts"
click node_controller "https://github.com/voidcosmos/npkill/blob/main/src/cli/cli.controller.ts"
click node_scanner "https://github.com/voidcosmos/npkill/blob/main/src/cli/services/scan.service.ts"
click node_engine "https://github.com/voidcosmos/npkill/blob/main/src/core/npkill.ts"
click node_worker_manager "https://github.com/voidcosmos/npkill/blob/main/src/core/services/files/files.worker.service.ts"
click node_worker "https://github.com/voidcosmos/npkill/blob/main/src/core/services/files/files.worker.ts"
click node_logger "https://github.com/voidcosmos/npkill/blob/main/src/core/services/logger.service.ts"
click node_console "https://github.com/voidcosmos/npkill/blob/main/src/cli/services/console.service.ts"
click node_ui_service "https://github.com/voidcosmos/npkill/blob/main/src/cli/services/ui.service.ts"
click node_results_ui "https://github.com/voidcosmos/npkill/blob/main/src/cli/ui/components/results.ui.ts"
click node_header_ui "https://github.com/voidcosmos/npkill/blob/main/src/cli/ui/components/header/stats.ui.ts"
click node_help_ui "https://github.com/voidcosmos/npkill/blob/main/src/cli/ui/components/help/help.ui.ts"
click node_details_ui "https://github.com/voidcosmos/npkill/blob/main/src/cli/ui/components/result-details.ui.ts"
click node_results "https://github.com/voidcosmos/npkill/blob/main/src/cli/services/results.service.ts"
click node_json "https://github.com/voidcosmos/npkill/blob/main/src/cli/services/json-output.service.ts"
click node_config "https://github.com/voidcosmos/npkill/blob/main/src/core/services/config.service.ts"
click node_profiles "https://github.com/voidcosmos/npkill/blob/main/src/core/services/profiles.service.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_entry,node_controller,node_console,node_user toneBlue
class node_scanner,node_engine,node_worker_manager,node_worker,node_logger toneAmber
class node_ui_service,node_results_ui,node_header_ui,node_help_ui,node_details_ui toneMint
class node_results,node_json toneRose
class node_config,node_profiles,node_filesystem,node_terminal toneIndigo
```

## Components

### CLI startup

- [CLI entry](https://github.com/voidcosmos/npkill/blob/main/src/main.ts): `src/main.ts`
- [Command controller](https://github.com/voidcosmos/npkill/blob/main/src/cli/cli.controller.ts): `src/cli/cli.controller.ts`
- [Argument parser](https://github.com/voidcosmos/npkill/blob/main/src/cli/services/console.service.ts): `src/cli/services/console.service.ts`

### Discovery and analysis

- [Scan service](https://github.com/voidcosmos/npkill/blob/main/src/cli/services/scan.service.ts): `src/cli/services/scan.service.ts`
- [Scan engine](https://github.com/voidcosmos/npkill/blob/main/src/core/npkill.ts): `src/core/npkill.ts`
- [Worker manager](https://github.com/voidcosmos/npkill/blob/main/src/core/services/files/files.worker.service.ts): `src/core/services/files/files.worker.service.ts`
- [File worker](https://github.com/voidcosmos/npkill/blob/main/src/core/services/files/files.worker.ts): `src/core/services/files/files.worker.ts`
- [Logger](https://github.com/voidcosmos/npkill/blob/main/src/core/services/logger.service.ts): `src/core/services/logger.service.ts`

### Interactive experience

- [UI coordinator](https://github.com/voidcosmos/npkill/blob/main/src/cli/services/ui.service.ts): `src/cli/services/ui.service.ts`
- [Results panel](https://github.com/voidcosmos/npkill/blob/main/src/cli/ui/components/results.ui.ts): `src/cli/ui/components/results.ui.ts`
- [Header and stats](https://github.com/voidcosmos/npkill/blob/main/src/cli/ui/components/header/stats.ui.ts): `src/cli/ui/components/header/stats.ui.ts`
- [Help panel](https://github.com/voidcosmos/npkill/blob/main/src/cli/ui/components/help/help.ui.ts): `src/cli/ui/components/help/help.ui.ts`
- [Result details](https://github.com/voidcosmos/npkill/blob/main/src/cli/ui/components/result-details.ui.ts): `src/cli/ui/components/result-details.ui.ts`

### Results and output

- [Result tracking](https://github.com/voidcosmos/npkill/blob/main/src/cli/services/results.service.ts): `src/cli/services/results.service.ts`
- [JSON output](https://github.com/voidcosmos/npkill/blob/main/src/cli/services/json-output.service.ts): `src/cli/services/json-output.service.ts`

### Configuration

- [Config loader](https://github.com/voidcosmos/npkill/blob/main/src/core/services/config.service.ts): `src/core/services/config.service.ts`
- [Profile service](https://github.com/voidcosmos/npkill/blob/main/src/core/services/profiles.service.ts): `src/core/services/profiles.service.ts`

### Other components

- **CLI user**
- **Local filesystem**
- **Terminal**

## Connections

- CLI user → CLI entry: runs command (evidence: `README.md`)
- CLI entry → Command controller: starts (evidence: `src/main.ts`)
- CLI entry → Logger: creates (evidence: `src/main.ts`)
- CLI entry → Result tracking: creates (evidence: `src/main.ts`)
- CLI entry → Config loader: creates (evidence: `src/main.ts`)
- CLI entry → Profile service: creates (evidence: `src/main.ts`)
- CLI entry → Scan service: creates (evidence: `src/main.ts`)
- CLI entry → JSON output: creates (evidence: `src/main.ts`)
- CLI entry → Argument parser: creates (evidence: `src/main.ts`)
- CLI entry → UI coordinator: creates (evidence: `src/main.ts`)
- Command controller → Scan service: requests scan (evidence: `src/cli/cli.controller.ts`)
- Scan service → Scan engine: starts scan (evidence: `src/cli/services/scan.service.ts`)
- Scan service → Scan engine: gets size and age (evidence: `src/cli/services/scan.service.ts`)
- Command controller → Result tracking: tracks results (evidence: `src/cli/cli.controller.ts`)
- Command controller → JSON output: processes scan output (evidence: `src/cli/cli.controller.ts`)
- Command controller → UI coordinator: renders interface (evidence: `src/cli/cli.controller.ts`)
- Command controller → Results panel: registers panel (evidence: `src/cli/cli.controller.ts`)
- Command controller → Result details: opens details (evidence: `src/cli/cli.controller.ts`)
- Command controller → Help panel: shows help (evidence: `src/cli/cli.controller.ts`)
- Command controller → Header and stats: registers stats (evidence: `src/cli/cli.controller.ts`)
- Results panel → Result tracking: reads results (evidence: `src/cli/ui/components/results.ui.ts`)
- Command controller → Scan engine: deletes folder (evidence: `src/cli/cli.controller.ts`)
- Worker manager → File worker: dispatches jobs (evidence: `src/core/services/files/files.worker.service.ts`)
- Worker manager → Logger: logs errors (evidence: `src/core/services/files/files.worker.service.ts`)
- Scan engine → Local filesystem: scans and deletes
- Command controller → Config loader: uses settings
- Command controller → Profile service: selects profiles
- JSON output → Terminal: writes output
- UI coordinator → Terminal: draws interface
