# rowkavdev/ghostdeps architecture

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

- Interactive diagram: https://gitdiagram.com/rowkavdev/ghostdeps
- Repository: https://github.com/rowkavdev/ghostdeps

## Overview

GhostDeps statically compares declared dependencies with evidence from manifests, lockfiles, and source, then reports findings with confidence and limitations. Its main workflow is repository scan → ecosystem-specific detection and usage analysis → findings and recommendations → CLI or GitHub check output. The README also documents two PR integrations: a GitHub App and a GitHub Action. The tree and sampled excerpts support the main boundaries; some internal wiring and unsampled capability details are represented only where the documented workflow supports them.

Main entry points: [`packages/core/src/engine/analyse.ts`](https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/engine/analyse.ts) (Analysis engine), [`packages/github-app/src/worker/analyse-job.ts`](https://github.com/rowkavdev/ghostdeps/blob/main/packages/github-app/src/worker/analyse-job.ts) (Analysis worker), [`packages/core/src/engine/run-adapter.ts`](https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/engine/run-adapter.ts) (Adapter runtime), [`packages/cli/src/scan.ts`](https://github.com/rowkavdev/ghostdeps/blob/main/packages/cli/src/scan.ts) (CLI scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[cli.ts]"]
  node_cli_scan["CLI scan<br/>[scan.ts]"]
  node_action["Action entry<br/>[index.ts]"]
  node_action_post["Action check poster<br/>[post-check.ts]"]
end

subgraph group_analysis["Analysis engine"]
  node_scanner["Repository scanner<br/>[scanner.ts]"]
  node_analysis_engine["Analysis engine<br/>[analyse.ts]"]
  node_adapter_runtime["Adapter runtime<br/>[run-adapter.ts]"]
  node_impact["Dependency impact<br/>[impact.ts]"]
  node_recommendations["Recommendation policy<br/>[index.ts]"]
  node_report["Result reporting<br/>[index.ts]"]
end

subgraph group_adapters["Ecosystem adapters"]
  node_js_adapter["JS/TS adapter<br/>[adapter.ts]"]
  node_python_adapter["Python adapter<br/>[adapter.ts]"]
  node_rust_adapter["Rust adapter<br/>[adapter.ts]"]
  node_go_adapter["Go adapter<br/>[adapter.ts]"]
end

subgraph group_github["GitHub integrations"]
  node_github_app["GitHub App<br/>[app.ts]"]
  node_jobs["Job queue<br/>[jobs.ts]"]
  node_app_worker["Analysis worker<br/>[analyse-job.ts]"]
  node_checkout["Repository checkout<br/>[index.ts]"]
  node_check_renderer["Check renderer<br/>[render.ts]"]
  node_app_reporter["Check reporter<br/>[reporter.ts]"]
  node_metadata["Registry metadata"]
end

node_developer(("Developer"))
node_pull_request(("Pull request"))
node_repository["Source repository"]

node_developer -->|"runs"| node_cli
node_cli -->|"starts scan"| node_cli_scan
node_cli_scan -->|"requests analysis"| node_analysis_engine
node_repository -->|"provides files"| node_scanner
node_analysis_engine -->|"scans"| node_scanner
node_analysis_engine -->|"runs adapters"| node_adapter_runtime
node_adapter_runtime -->|"dispatches"| node_js_adapter
node_adapter_runtime -->|"dispatches"| node_python_adapter
node_adapter_runtime -->|"dispatches"| node_rust_adapter
node_adapter_runtime -->|"dispatches"| node_go_adapter
node_analysis_engine -->|"derives impact"| node_impact
node_analysis_engine -->|"applies policy"| node_recommendations
node_analysis_engine -->|"produces result"| node_report
node_cli_scan -->|"formats output"| node_report
node_pull_request -->|"triggers"| node_github_app
node_github_app -->|"enqueues"| node_jobs
node_github_app -->|"creates worker"| node_app_worker
node_jobs -->|"dispatches job"| node_app_worker
node_app_worker -->|"obtains source"| node_checkout
node_app_worker -->|"runs analysis"| node_analysis_engine
node_app_worker -.->|"requests facts"| node_metadata
node_app_worker -->|"renders result"| node_check_renderer
node_check_renderer -->|"supplies check output"| node_app_reporter
node_app_reporter -->|"posts check"| node_pull_request
node_action -->|"runs analysis"| node_cli_scan
node_action -->|"posts result"| node_action_post
node_action_post -->|"renders result"| node_check_renderer
node_action_post -->|"creates check"| node_pull_request

click node_cli "https://github.com/rowkavdev/ghostdeps/blob/main/packages/cli/src/cli.ts"
click node_cli_scan "https://github.com/rowkavdev/ghostdeps/blob/main/packages/cli/src/scan.ts"
click node_action "https://github.com/rowkavdev/ghostdeps/blob/main/packages/action/src/index.ts"
click node_action_post "https://github.com/rowkavdev/ghostdeps/blob/main/packages/action/src/post-check.ts"
click node_scanner "https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/engine/scanner/scanner.ts"
click node_analysis_engine "https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/engine/analyse.ts"
click node_adapter_runtime "https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/engine/run-adapter.ts"
click node_impact "https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/engine/impact.ts"
click node_recommendations "https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/recommend/index.ts"
click node_report "https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/report/index.ts"
click node_js_adapter "https://github.com/rowkavdev/ghostdeps/blob/main/packages/adapters/javascript-typescript/src/adapter.ts"
click node_python_adapter "https://github.com/rowkavdev/ghostdeps/blob/main/packages/adapters/python/src/adapter.ts"
click node_rust_adapter "https://github.com/rowkavdev/ghostdeps/blob/main/packages/adapters/rust/src/adapter.ts"
click node_go_adapter "https://github.com/rowkavdev/ghostdeps/blob/main/packages/adapters/go/src/adapter.ts"
click node_github_app "https://github.com/rowkavdev/ghostdeps/blob/main/packages/github-app/src/app.ts"
click node_jobs "https://github.com/rowkavdev/ghostdeps/blob/main/packages/github-app/src/jobs.ts"
click node_app_worker "https://github.com/rowkavdev/ghostdeps/blob/main/packages/github-app/src/worker/analyse-job.ts"
click node_checkout "https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/checkout/index.ts"
click node_check_renderer "https://github.com/rowkavdev/ghostdeps/blob/main/packages/checks-renderer/src/render.ts"
click node_app_reporter "https://github.com/rowkavdev/ghostdeps/blob/main/packages/github-app/src/checks/reporter.ts"
click node_metadata "https://github.com/rowkavdev/ghostdeps/blob/main/packages/github-app/src/worker/registry-metadata.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_cli,node_cli_scan,node_action,node_action_post toneBlue
class node_scanner,node_analysis_engine,node_adapter_runtime,node_impact,node_recommendations,node_report toneAmber
class node_js_adapter,node_python_adapter,node_rust_adapter,node_go_adapter,node_pull_request toneMint
class node_github_app,node_jobs,node_app_worker,node_checkout,node_check_renderer,node_app_reporter,node_metadata toneRose
class node_developer,node_repository toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/rowkavdev/ghostdeps/blob/main/packages/cli/src/cli.ts): `packages/cli/src/cli.ts`
- [CLI scan](https://github.com/rowkavdev/ghostdeps/blob/main/packages/cli/src/scan.ts): `packages/cli/src/scan.ts`
- [Action entry](https://github.com/rowkavdev/ghostdeps/blob/main/packages/action/src/index.ts): `packages/action/src/index.ts`
- [Action check poster](https://github.com/rowkavdev/ghostdeps/blob/main/packages/action/src/post-check.ts): `packages/action/src/post-check.ts`

### Analysis engine

- [Repository scanner](https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/engine/scanner/scanner.ts): `packages/core/src/engine/scanner/scanner.ts`
- [Analysis engine](https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/engine/analyse.ts): `packages/core/src/engine/analyse.ts`
- [Adapter runtime](https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/engine/run-adapter.ts): `packages/core/src/engine/run-adapter.ts`
- [Dependency impact](https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/engine/impact.ts): `packages/core/src/engine/impact.ts`
- [Recommendation policy](https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/recommend/index.ts): `packages/core/src/recommend/index.ts`
- [Result reporting](https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/report/index.ts): `packages/core/src/report/index.ts`

### Ecosystem adapters

- [JS/TS adapter](https://github.com/rowkavdev/ghostdeps/blob/main/packages/adapters/javascript-typescript/src/adapter.ts): `packages/adapters/javascript-typescript/src/adapter.ts`
- [Python adapter](https://github.com/rowkavdev/ghostdeps/blob/main/packages/adapters/python/src/adapter.ts): `packages/adapters/python/src/adapter.ts`
- [Rust adapter](https://github.com/rowkavdev/ghostdeps/blob/main/packages/adapters/rust/src/adapter.ts): `packages/adapters/rust/src/adapter.ts`
- [Go adapter](https://github.com/rowkavdev/ghostdeps/blob/main/packages/adapters/go/src/adapter.ts): `packages/adapters/go/src/adapter.ts`

### GitHub integrations

- [GitHub App](https://github.com/rowkavdev/ghostdeps/blob/main/packages/github-app/src/app.ts): `packages/github-app/src/app.ts`
- [Job queue](https://github.com/rowkavdev/ghostdeps/blob/main/packages/github-app/src/jobs.ts): `packages/github-app/src/jobs.ts`
- [Analysis worker](https://github.com/rowkavdev/ghostdeps/blob/main/packages/github-app/src/worker/analyse-job.ts): `packages/github-app/src/worker/analyse-job.ts`
- [Repository checkout](https://github.com/rowkavdev/ghostdeps/blob/main/packages/core/src/checkout/index.ts): `packages/core/src/checkout/index.ts`
- [Check renderer](https://github.com/rowkavdev/ghostdeps/blob/main/packages/checks-renderer/src/render.ts): `packages/checks-renderer/src/render.ts`
- [Check reporter](https://github.com/rowkavdev/ghostdeps/blob/main/packages/github-app/src/checks/reporter.ts): `packages/github-app/src/checks/reporter.ts`
- [Registry metadata](https://github.com/rowkavdev/ghostdeps/blob/main/packages/github-app/src/worker/registry-metadata.ts): `packages/github-app/src/worker/registry-metadata.ts`

### Other components

- **Developer**
- **Pull request**
- **Source repository**

## Connections

- Developer → CLI commands: runs
- CLI commands → CLI scan: starts scan
- CLI scan → Analysis engine: requests analysis
- Source repository → Repository scanner: provides files
- Analysis engine → Repository scanner: scans
- Analysis engine → Adapter runtime: runs adapters
- Adapter runtime → JS/TS adapter: dispatches
- Adapter runtime → Python adapter: dispatches
- Adapter runtime → Rust adapter: dispatches
- Adapter runtime → Go adapter: dispatches
- Analysis engine → Dependency impact: derives impact
- Analysis engine → Recommendation policy: applies policy
- Analysis engine → Result reporting: produces result
- CLI scan → Result reporting: formats output
- Pull request → GitHub App: triggers
- GitHub App → Job queue: enqueues
- GitHub App → Analysis worker: creates worker
- Job queue → Analysis worker: dispatches job
- Analysis worker → Repository checkout: obtains source
- Analysis worker → Analysis engine: runs analysis
- Analysis worker → Registry metadata: requests facts
- Analysis worker → Check renderer: renders result
- Check renderer → Check reporter: supplies check output
- Check reporter → Pull request: posts check
- Action entry → CLI scan: runs analysis
- Action entry → Action check poster: posts result
- Action check poster → Check renderer: renders result
- Action check poster → Pull request: creates check