# pranshuparmar/witr architecture

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

- Interactive diagram: https://gitdiagram.com/pranshuparmar/witr
- Repository: https://github.com/pranshuparmar/witr

## Overview

1. **What this repo is**
   - `witr` is a cross-platform Go CLI and terminal UI that explains “why is this running?” by tracing a running thing back to the process, service, container, shell, or scheduler responsible for it.

2. **Entry points and startup**
   - The executable starts in `main.go` / `cmd/witr/main.go`, which hand off to the app layer in `internal/app`.
   - The app layer parses flags, decides between one-shot output vs interactive TUI, and routes the request into the analysis pipeline.

3. **Shared domain model**
   - `pkg/model` is the stable data contract between all subsystems.
   - It defines the normalized objects the rest of the repo works with: `Process`, `Container`, `Source`, `Target`, `Result`, `Socket`, `Net`, `Lock`, `Resource`, and file-context metadata.
   - This keeps OS-specific collection code separate from output and UI rendering.

4. **Target resolution layer**
   - `internal/target` turns user input into concrete lookup targets.
   - It resolves names, PIDs, ports, files, and container references into the canonical target set the analyzer can process.
   - This is the boundary between “user intent” and “system facts.”

5. **Process and system introspection layer**
   - `internal/proc` is the largest subsystem and contains the OS adapters for process discovery, ancestry, command lines, environments, open files, sockets, locks, resource usage, and boot/runtime details.
   - It is heavily split by platform: Linux leans on `/proc`, macOS on `ps`/`lsof`/`sysctl` and libproc, Windows on Win32 APIs, and FreeBSD on `procstat`/`ps`/`lsof`.
   - This layer also includes container/runtime detection helpers and wrappers for Docker-like runtimes and system services.

6. **Source attribution / “why” classification**
   - `internal/source` interprets the collected facts and decides what primary system explains the process’s existence.
   - It covers supervisors and launch mechanisms such as systemd, launchd, cron, shells, SSH sessions, container runtimes, Windows services, and BSD rc-style sources.
   - The output deliberately chooses one primary source while still allowing warnings and secondary context.

7. **Analysis pipeline**
   - `internal/pipeline/analyze.go` is the central orchestrator that combines targets, process facts, source attribution, and warnings into final results.
   - This is where the repo’s causal model is assembled: “target → PID(s) → ancestry → source → context → warnings.”

8. **Output rendering subsystem**
   - `internal/output` renders the same result model into multiple presentations: standard narrative text, short form, tree view, JSON, environment-only output, warnings-only output, and Docker/container-specific formatting.
   - It includes color handling, sanitization, and safe writing so sensitive or malformed content is controlled before reaching the terminal.
   - This subsystem is intentionally decoupled from collection logic so the same analysis can serve CLI, scripting, and TUI use cases.

9. **Interactive TUI**
   - `internal/tui` provides the dashboard mode with tabs for processes, ports, containers, and locks.
   - It reuses the same underlying data model as the CLI, but adds live navigation, filtering, selection, and process actions such as signal/renice on Unix-like systems.
   - The TUI is a view/update/action layer over the same analysis and proc data, not a separate code path.

10. **Platform-specific boundaries and external dependencies**
   - Platform behavior is isolated using build tags throughout `internal/proc`, `internal/source`, `internal/target`, `internal/output`, and `internal/tui`.
   - The main external boundary is the host operating system and its native APIs or command-line tools; container lookup may also depend on runtime CLIs such as Docker, Podman, nerdctl, crictl, or FreeBSD jail tooling being available on `PATH`.
   - `internal/launchd` and `internal/tools/docgen` are support subsystems for macOS plist parsing and documentation generation, while the `.github`, `goreleaser`, and install scripts support release/distribution rather than runtime behavior.

Main entry points: [`internal/pipeline/analyze.go`](https://github.com/pranshuparmar/witr/blob/main/internal/pipeline/analyze.go) (Analyze), [`pkg/model/result.go`](https://github.com/pranshuparmar/witr/blob/main/pkg/model/result.go) (Model), [`internal/app/app.go`](https://github.com/pranshuparmar/witr/blob/main/internal/app/app.go) (App), [`internal/source/detect.go`](https://github.com/pranshuparmar/witr/blob/main/internal/source/detect.go) (Detect)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry"]
  node_main["Main<br/>cli entry<br/>[main.go]"]
  node_cmd_main["Witr cmd<br/>cli entry<br/>[main.go]"]
  node_version["Version<br/>metadata<br/>[version.go]"]
end

subgraph group_core["Core"]
  node_app["App<br/>orchestration<br/>[app.go]"]
  node_target["Targeting<br/>resolver<br/>[resolve.go]"]
  node_pipeline["Analyze<br/>pipeline<br/>[analyze.go]"]
  node_model[("Model<br/>domain contract<br/>[result.go]")]
end

subgraph group_proc["Proc"]
  node_process["Processes<br/>proc core<br/>[process_linux.go]"]
  node_runtime["Runtime"]
  node_system["System I/O<br/>proc io<br/>[net_linux.go]"]
  node_boot["Boot & Users<br/>proc env<br/>[boot_linux.go]"]
end

subgraph group_source["Source"]
  node_source_detect["Detect<br/>attribution<br/>[detect.go]"]
  node_source_supervisor["Supervisors<br/>attribution<br/>[supervisor.go]"]
  node_source_container["Containers<br/>attribution<br/>[container.go]"]
  node_source_network["Network<br/>attribution<br/>[network.go]"]
end

subgraph group_present["Presentation"]
  node_output["Output<br/>rendering<br/>[printer.go]"]
  node_tui["TUI<br/>interactive ui<br/>[model.go]"]
end

subgraph group_support["Support"]
  node_launchd["Launchd<br/>macos support<br/>[plist.go]"]
  node_docgen["Docgen<br/>tooling<br/>[main.go]"]
end

node_main -->|"delegates"| node_cmd_main
node_cmd_main -->|"starts"| node_app
node_app -->|"resolves"| node_target
node_app -->|"analyzes"| node_pipeline
node_app -->|"renders"| node_output
node_app -->|"interactive mode"| node_tui
node_pipeline -->|"produces"| node_model
node_pipeline -->|"queries"| node_process
node_pipeline -->|"checks"| node_runtime
node_pipeline -->|"collects"| node_system
node_pipeline -->|"classifies"| node_source_detect
node_process -->|"normalizes"| node_model
node_runtime -->|"normalizes"| node_model
node_system -->|"normalizes"| node_model
node_boot -->|"supports"| node_process
node_source_detect -->|"uses"| node_source_supervisor
node_source_detect -->|"uses"| node_source_container
node_source_detect -->|"uses"| node_source_network
node_source_detect -->|"emits"| node_model
node_output -->|"reads"| node_model
node_tui -->|"reads"| node_model
node_launchd -->|"supports"| node_source_supervisor
node_docgen -.->|"documents"| node_output
node_version -->|"configures"| node_app

click node_main "https://github.com/pranshuparmar/witr/blob/main/main.go"
click node_cmd_main "https://github.com/pranshuparmar/witr/blob/main/cmd/witr/main.go"
click node_app "https://github.com/pranshuparmar/witr/blob/main/internal/app/app.go"
click node_target "https://github.com/pranshuparmar/witr/blob/main/internal/target/resolve.go"
click node_pipeline "https://github.com/pranshuparmar/witr/blob/main/internal/pipeline/analyze.go"
click node_model "https://github.com/pranshuparmar/witr/blob/main/pkg/model/result.go"
click node_process "https://github.com/pranshuparmar/witr/blob/main/internal/proc/process_linux.go"
click node_runtime "https://github.com/pranshuparmar/witr/blob/main/internal/proc/runtime_dockerlike.go"
click node_system "https://github.com/pranshuparmar/witr/blob/main/internal/proc/net_linux.go"
click node_boot "https://github.com/pranshuparmar/witr/blob/main/internal/proc/boot_linux.go"
click node_source_detect "https://github.com/pranshuparmar/witr/blob/main/internal/source/detect.go"
click node_source_supervisor "https://github.com/pranshuparmar/witr/blob/main/internal/source/supervisor.go"
click node_source_container "https://github.com/pranshuparmar/witr/blob/main/internal/source/container.go"
click node_source_network "https://github.com/pranshuparmar/witr/blob/main/internal/source/network.go"
click node_output "https://github.com/pranshuparmar/witr/blob/main/internal/output/printer.go"
click node_tui "https://github.com/pranshuparmar/witr/blob/main/internal/tui/model.go"
click node_launchd "https://github.com/pranshuparmar/witr/blob/main/internal/launchd/plist.go"
click node_docgen "https://github.com/pranshuparmar/witr/blob/main/internal/tools/docgen/main.go"
click node_version "https://github.com/pranshuparmar/witr/blob/main/internal/version/version.go"

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_cmd_main,node_version toneBlue
class node_app,node_target,node_pipeline,node_model toneAmber
class node_process,node_runtime,node_system,node_boot toneMint
class node_source_detect,node_source_supervisor,node_source_container,node_source_network toneRose
class node_output,node_tui toneIndigo
class node_launchd,node_docgen toneTeal
```

## Components

### Entry

CLI startup and versioning

- [Main](https://github.com/pranshuparmar/witr/blob/main/main.go): cli entry · Process startup and handoff · `main.go`
- [Witr cmd](https://github.com/pranshuparmar/witr/blob/main/cmd/witr/main.go): cli entry · Command bootstrap and unsupported build handling · `cmd/witr/main.go`
- [Version](https://github.com/pranshuparmar/witr/blob/main/internal/version/version.go): metadata · Build and release version information · `internal/version/version.go`

### Core

Targeting, analysis, and shared domain model

- [App](https://github.com/pranshuparmar/witr/blob/main/internal/app/app.go): orchestration · Parses flags and selects execution mode · `internal/app/app.go`
- [Targeting](https://github.com/pranshuparmar/witr/blob/main/internal/target/resolve.go): resolver · Resolves names, PIDs, ports, files, and containers · `internal/target/resolve.go`
- [Analyze](https://github.com/pranshuparmar/witr/blob/main/internal/pipeline/analyze.go): pipeline · Builds final explanation from targets and facts · `internal/pipeline/analyze.go`
- [Model](https://github.com/pranshuparmar/witr/blob/main/pkg/model/result.go): domain contract · Shared normalized result and fact types · `pkg/model/result.go`

### Proc

OS and runtime introspection

- [Processes](https://github.com/pranshuparmar/witr/blob/main/internal/proc/process_linux.go): proc core · Process discovery, ancestry, command lines, env, and files · `internal/proc/process_linux.go`
- [Runtime](https://github.com/pranshuparmar/witr/blob/main/internal/proc/runtime_dockerlike.go): container/runtime · Container and jail runtime detection · `internal/proc/runtime_dockerlike.go`
- [System I/O](https://github.com/pranshuparmar/witr/blob/main/internal/proc/net_linux.go): proc io · Sockets, locks, resources, and open files · `internal/proc/net_linux.go`
- [Boot & Users](https://github.com/pranshuparmar/witr/blob/main/internal/proc/boot_linux.go): proc env · Boot time, sessions, and user context · `internal/proc/boot_linux.go`

### Source

Why-this-runs attribution

- [Detect](https://github.com/pranshuparmar/witr/blob/main/internal/source/detect.go): attribution · Chooses the primary explanation source · `internal/source/detect.go`
- [Supervisors](https://github.com/pranshuparmar/witr/blob/main/internal/source/supervisor.go): attribution · Systemd, launchd, cron, shell, SSH, and services · `internal/source/supervisor.go`
- [Containers](https://github.com/pranshuparmar/witr/blob/main/internal/source/container.go): attribution · Container and runtime-based attribution · `internal/source/container.go`
- [Network](https://github.com/pranshuparmar/witr/blob/main/internal/source/network.go): attribution · Port and socket-based attribution · `internal/source/network.go`

### Presentation

CLI and TUI rendering

- [Output](https://github.com/pranshuparmar/witr/blob/main/internal/output/printer.go): rendering · Text, JSON, tree, short, and env-only output · `internal/output/printer.go`
- [TUI](https://github.com/pranshuparmar/witr/blob/main/internal/tui/model.go): interactive ui · Interactive dashboard and process actions · `internal/tui/model.go`

### Support

Launchd and docs tooling

- [Launchd](https://github.com/pranshuparmar/witr/blob/main/internal/launchd/plist.go): macos support · macOS plist parsing support · `internal/launchd/plist.go`
- [Docgen](https://github.com/pranshuparmar/witr/blob/main/internal/tools/docgen/main.go): tooling · CLI documentation generation · `internal/tools/docgen/main.go`

## Connections

- Main → Witr cmd: delegates · Top-level entry hands off to command bootstrap
- Witr cmd → App: starts · Bootstraps the application layer
- App → Targeting: resolves · Turns user input into canonical targets
- App → Analyze: analyzes · Runs the causal analysis pipeline
- App → Output: renders · Sends results to the selected output format
- App → TUI: interactive mode · Switches to dashboard mode when requested
- Analyze → Model: produces · Assembles the shared result model
- Analyze → Processes: queries · Collects process and ancestry facts
- Analyze → Runtime: checks · Looks for container and runtime context
- Analyze → System I/O: collects · Uses sockets, locks, files, and resource data
- Analyze → Detect: classifies · Chooses the primary explanation source
- Processes → Model: normalizes · Maps OS-specific facts into shared types
- Runtime → Model: normalizes · Feeds container/runtime facts into shared types
- System I/O → Model: normalizes · Feeds I/O and resource facts into shared types
- Boot & Users → Processes: supports · Provides host boot and user context
- Detect → Supervisors: uses · Delegates to supervisor and launch source classifiers
- Detect → Containers: uses · Delegates to container attribution
- Detect → Network: uses · Delegates to port and socket attribution
- Detect → Model: emits · Writes source and warning context into the result model
- Output → Model: reads · Renders the shared result contract in multiple formats
- TUI → Model: reads · Uses the same underlying data model as CLI output
- Launchd → Supervisors: supports · Used by macOS launchd attribution paths
- Docgen → Output: documents · Generates CLI documentation from command behavior
- Version → App: configures · Provides version metadata to the application