# aashmit-mckenzie-college/hunter architecture

> Architecture diagram of the GitHub repository aashmit-mckenzie-college/hunter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aashmit-mckenzie-college/hunter
- Repository: https://github.com/aashmit-mckenzie-college/hunter

## Overview

1. **What this repo is**
   - Hunter is a **local-first static analysis platform** for PHP codebases, with **WordPress as a first-class profile**.
   - The core runtime is the Python package under `src/hunter`; the UI is a separate React/Vite dashboard in `dashboard/`.

2. **Main entrypoints**
   - **CLI**: `src/hunter/cli/main.py` runs scans directly against a path.
   - **API backend**: `src/hunter/api/main.py` exposes scan/upload/GitHub endpoints for the dashboard.
   - **Dashboard**: the React app talks only to the API; it is not the analysis engine.

3. **Primary scan flow**
   - The default pipeline is: **ingestion → parse + lift → graph construction → catalog/adapters → analysis → rule evaluation → enrichment → reports**.
   - This is the deterministic static path described in the README; everything else layers on top of it.

4. **Ingestion boundary**
   - `src/hunter/ingest/` walks the target tree, applies limits, and writes a snapshot/manifest of the codebase.
   - This stage defines the “what is being analyzed” boundary and feeds the rest of the system with a bounded, reproducible file set.

5. **Parsing and semantic lift**
   - `src/hunter/parse/` handles language detection, parsing, line indexing, and export of the intermediate representation.
   - The lift code (`lift.py`, `lift_v2.py`) produces the **IR v2** semantic layer that downstream graph and analysis components consume.
   - Parsing is parallelized with worker infrastructure in `src/hunter/concurrency/`.

6. **Graph substrate**
   - `src/hunter/graph/` is the structural backbone: graph building, integrity checks, layered schema support, imports, and exports.
   - The repo carries **graph migrations** and uses a **schema v3 / layered graph** model; Neo4j integration exists for graph metadata/bulk export, but the analysis pipeline also works with in-memory graph structures.
   - The graph is the shared contract between parsing, semantic resolution, taint, and rule evaluation.

7. **Semantic and security analysis**
   - `src/hunter/analysis/semantic/` adds CFG, SSA, resolver logic, and interprocedural linking.
   - `src/hunter/analysis/taint/` performs path-sensitive taint analysis.
   - `src/hunter/analysis/security/` and `src/hunter/verify_static/` hold higher-level security reasoning and static verification hooks.
   - WordPress-specific behavior lives in `src/hunter/wp/` and is injected through profile/adaptor logic rather than hardcoded into the generic PHP path.

8. **Rules and profiles**
   - Rule evaluation is YAML-driven under `src/hunter/analysis/rules/`, with catalogs and packs for **generic PHP**, **WordPress**, and **full** scans.
   - The system uses graph queries and evaluators to map findings to metadata like **OWASP/CWE** and to switch behavior based on scan profile (`auto`, `generic-php`, `wordpress`, `full`).

9. **Confidence, enrichment, and gating**
   - `src/hunter/confidence/` computes confidence scores from weights/config.
   - `src/hunter/agents/` contains the enrichment and verification scaffolding, including gates and LLM-backed helpers.
   - In the default product, these components annotate or filter findings after deterministic analysis; in agent mode they can add additional reasoning, but they are deliberately separated from the core scanner.

10. **Reporting and artifacts**
   - `src/hunter/reporting/` turns findings into grouped human-readable summaries.
   - The pipeline writes artifacts to `output/<scan>/`, including **findings JSON**, **grouped triage reports**, **evidence excerpts**, and **semantic graph exports**.
   - This output directory is the main boundary between the analysis engine and consumers.

11. **Persistence and dashboard backend**
   - `src/hunter/persistence/` stores scan/job state in **SQLite or Postgres**.
   - `src/hunter/api/services/scan_worker.py` runs scans in a background process for the dashboard.
   - The API also integrates with GitHub cloning and PDF report generation, making the backend a thin orchestration layer around the same scan engine.

12. **Configuration and external dependencies**
   - Runtime behavior is driven by `config/default.yaml` plus environment variables.
   - Optional external services include:
     - **GitHub** for cloning/importing repos into scans.
     - **LLM providers** for agent mode, configured separately in `config/agents.local.yaml`.
     - **Neo4j** for graph-related metadata/export paths.
   - The README emphasizes that agent configuration is file-only and gated by `hunter agents test`.

13. **Operational shape**
   - The system is designed for **deterministic, reproducible local scans** with parallel parsing/ingestion and serial high-risk steps like CFG/taint when needed.
   - Observability hooks exist in `src/hunter/observability/`, and the repo includes tests/fixtures for PHP and WordPress inputs to validate the analysis pipeline end to end.

Main entry points: [`src/hunter/analysis/rules`](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/analysis/rules) (Rules engine), [`src/hunter/graph`](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/graph) (Graph core), [`src/hunter/parse`](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/parse) (Parsing), [`src/hunter/orchestration`](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/orchestration) (Orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core engine"]
  node_cli["CLI<br/>entrypoint<br/>[main.py]"]
  node_ingest["Ingestion<br/>file boundary"]
  node_parse["Parsing<br/>language frontend"]
  node_lift["IR lift<br/>semantic lift<br/>[lift_v2.py]"]
  node_graph[("Graph core<br/>graph substrate")]
  node_semantic["Semantic analysis<br/>analysis stage"]
  node_taint["Taint analysis<br/>analysis stage"]
  node_security["Security checks<br/>analysis stage"]
  node_rules["Rules engine<br/>policy evaluation"]
  node_reporting["Reporting<br/>artifact formatter"]
  node_wordpress["WordPress profile<br/>domain adapter"]
end

subgraph group_web["Dashboard stack"]
  node_api["API<br/>http backend<br/>[main.py]"]
  node_worker["Scan worker<br/>background runner<br/>[scan_worker.py]"]
  node_dashboard["Dashboard<br/>react app<br/>[App.tsx]"]
  node_github["GitHub import<br/>external integration<br/>[github_client.py]"]
end

subgraph group_ops["Platform support"]
  node_confidence(("Confidence<br/>scoring engine<br/>[engine.py]"))
  node_agents["Agents<br/>enrichment layer"]
  node_persistence[("Persistence<br/>job store")]
  node_orchestration["Orchestration<br/>scan control"]
  node_settings["Config<br/>[settings.py]"]
  node_observability["Observability<br/>telemetry"]
  node_neo4j[("Neo4j export<br/>graph integration<br/>[neo4j_client.py]")]
end

node_cli -->|"starts"| node_ingest
node_api -->|"dispatches"| node_worker
node_worker -->|"runs"| node_orchestration
node_dashboard -->|"calls"| node_api
node_github -->|"feeds"| node_api
node_orchestration -->|"coordinates"| node_ingest
node_ingest -->|"passes files"| node_parse
node_parse -->|"produces"| node_lift
node_parse -->|"exports"| node_graph
node_lift -->|"builds"| node_graph
node_graph -->|"supports"| node_semantic
node_semantic -->|"enables"| node_taint
node_semantic -->|"feeds"| node_security
node_graph -->|"queried by"| node_rules
node_taint -->|"produces findings"| node_rules
node_security -->|"augments"| node_rules
node_rules -->|"scores"| node_confidence
node_rules -->|"hands off"| node_agents
node_agents -->|"annotates"| node_reporting
node_rules -->|"renders"| node_reporting
node_reporting -->|"stores"| node_persistence
node_orchestration -->|"records"| node_persistence
node_settings -->|"configures"| node_api
node_settings -->|"configures"| node_cli
node_observability -->|"watches"| node_orchestration
node_graph -.->|"exports to"| node_neo4j
node_wordpress -->|"adapts"| node_parse
node_wordpress -->|"profiles"| node_rules

click node_cli "https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/cli/main.py"
click node_api "https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/api/main.py"
click node_worker "https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/api/services/scan_worker.py"
click node_dashboard "https://github.com/aashmit-mckenzie-college/hunter/blob/main/dashboard/src/App.tsx"
click node_ingest "https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/ingest"
click node_parse "https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/parse"
click node_lift "https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/parse/lift_v2.py"
click node_graph "https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/graph"
click node_semantic "https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/analysis/semantic"
click node_taint "https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/analysis/taint"
click node_security "https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/analysis/security"
click node_rules "https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/analysis/rules"
click node_confidence "https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/confidence/engine.py"
click node_agents "https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/agents"
click node_reporting "https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/reporting"
click node_persistence "https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/persistence"
click node_orchestration "https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/orchestration"
click node_settings "https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/settings.py"
click node_observability "https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/observability"
click node_github "https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/api/services/github_client.py"
click node_neo4j "https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/graph/neo4j_client.py"
click node_wordpress "https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/wp"

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_ingest,node_parse,node_lift,node_graph,node_semantic,node_taint,node_security,node_rules,node_reporting,node_wordpress toneBlue
class node_api,node_worker,node_dashboard,node_github toneAmber
class node_confidence,node_agents,node_persistence,node_orchestration,node_settings,node_observability,node_neo4j toneMint
```

## Components

### Core engine

Python analysis runtime and scan pipeline

- [CLI](https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/cli/main.py): entrypoint · Runs local scans against a path · `src/hunter/cli/main.py`
- [Ingestion](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/ingest): file boundary · Walks targets, applies limits, and snapshots input files · `src/hunter/ingest`
- [Parsing](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/parse): language frontend · Detects languages, parses PHP, and builds line indexes · `src/hunter/parse`
- [IR lift](https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/parse/lift_v2.py): semantic lift · Produces the v2 intermediate representation · `src/hunter/parse/lift_v2.py`
- [Graph core](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/graph): graph substrate · Builds the layered structural graph and validates integrity · `src/hunter/graph`
- [Semantic analysis](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/analysis/semantic): analysis stage · Constructs CFG, SSA, and resolver-linked semantics · `src/hunter/analysis/semantic`
- [Taint analysis](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/analysis/taint): analysis stage · Performs path-sensitive interprocedural taint tracking · `src/hunter/analysis/taint`
- [Security checks](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/analysis/security): analysis stage · Higher-level security reasoning and static verification hooks · `src/hunter/analysis/security`
- [Rules engine](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/analysis/rules): policy evaluation · Loads YAML packs and evaluates graph-driven findings · `src/hunter/analysis/rules`
- [Reporting](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/reporting): artifact formatter · Groups findings into human-readable summaries · `src/hunter/reporting`
- [WordPress profile](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/wp): domain adapter · Injects WordPress-specific semantics into the generic PHP pipeline · `src/hunter/wp`

### Dashboard stack

React UI and API orchestration

- [API](https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/api/main.py): http backend · Exposes scan, upload, and GitHub endpoints · `src/hunter/api/main.py`
- [Scan worker](https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/api/services/scan_worker.py): background runner · Executes scans for the dashboard backend · `src/hunter/api/services/scan_worker.py`
- [Dashboard](https://github.com/aashmit-mckenzie-college/hunter/blob/main/dashboard/src/App.tsx): react app · Browser UI for scan navigation and reports · `dashboard/src/App.tsx`
- [GitHub import](https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/api/services/github_client.py): external integration · Clones or imports repositories for scans · `src/hunter/api/services/github_client.py`

### Platform support

Persistence, config, observability, and external integrations

- [Confidence](https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/confidence/engine.py): scoring engine · Computes finding confidence from weights and config · `src/hunter/confidence/engine.py`
- [Agents](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/agents): enrichment layer · LLM-backed enrichment, gating, and verification scaffolding · `src/hunter/agents`
- [Persistence](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/persistence): job store · Stores scan and job state in SQLite or Postgres · `src/hunter/persistence`
- [Orchestration](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/orchestration): scan control · Coordinates scan lifecycle, status, and lineage · `src/hunter/orchestration`
- [Config](https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/settings.py): runtime config · Loads default YAML and environment-driven settings · `src/hunter/settings.py`
- [Observability](https://github.com/aashmit-mckenzie-college/hunter/tree/main/src/hunter/observability): telemetry · Metrics and tracing for pipeline execution · `src/hunter/observability`
- [Neo4j export](https://github.com/aashmit-mckenzie-college/hunter/blob/main/src/hunter/graph/neo4j_client.py): graph integration · Optional graph metadata and bulk export path · `src/hunter/graph/neo4j_client.py`

## Connections

- CLI → Ingestion: starts · CLI begins a local scan from a filesystem path
- API → Scan worker: dispatches · API hands scan jobs to the background worker
- Scan worker → Orchestration: runs · Worker uses orchestration to manage scan lifecycle
- Dashboard → API: calls · Dashboard reads and controls scans through the API
- GitHub import → API: feeds · GitHub integration supplies repo content to scan endpoints
- Orchestration → Ingestion: coordinates · Scan control kicks off bounded repository ingestion
- Ingestion → Parsing: passes files · Snapshot and manifest feed the parsing stage
- Parsing → IR lift: produces · Parsing emits the semantic IR v2 layer
- Parsing → Graph core: exports · Parser-derived structure is exported into graph form
- IR lift → Graph core: builds · Semantic lift is materialized into the shared graph substrate
- Graph core → Semantic analysis: supports · Structural graph is consumed by resolver and semantic analysis
- Semantic analysis → Taint analysis: enables · CFG, SSA, and resolution inform taint propagation
- Semantic analysis → Security checks: feeds · Semantic facts are reused by higher-level security checks
- Graph core → Rules engine: queried by · Rule packs evaluate findings through graph queries
- Taint analysis → Rules engine: produces findings · Taint results are scored and matched against rules
- Security checks → Rules engine: augments · Security reasoning contributes additional evaluation context
- Rules engine → Confidence: scores · Rules and findings are weighted into confidence scores
- Rules engine → Agents: hands off · Deterministic findings can be enriched or verified by agents
- Agents → Reporting: annotates · Agent outputs may filter or enrich report content
- Rules engine → Reporting: renders · Evaluated findings become grouped reports and summaries
- Reporting → Persistence: stores · Scan artifacts and job state are persisted for dashboard access
- Orchestration → Persistence: records · Lifecycle and status data are written to the job store
- Config → API: configures · Runtime settings drive backend behavior
- Config → CLI: configures · Runtime settings drive CLI scan behavior
- Observability → Orchestration: watches · Metrics and tracing observe scan execution
- Graph core → Neo4j export: exports to · Optional graph export and metadata integration
- WordPress profile → Parsing: adapts · WordPress-specific parsing and semantics extend the generic PHP path
- WordPress profile → Rules engine: profiles · WordPress rules and catalogs change evaluation behavior
