# calebevans/mulder architecture

> Architecture diagram of the GitHub repository calebevans/mulder, 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/calebevans/mulder
- Repository: https://github.com/calebevans/mulder

## Overview

Mulder is an autonomous digital-forensics investigation orchestrator and MCP server. An investigator starts a case from the CLI; the orchestrator runs cataloging, extraction, cross-system analysis, adversarial review, and reporting, using gated agent sessions and typed MCP tools. Evidence and findings are indexed in a per-case database and validated against an append-only audit trail before report and IOC/ATT&CK exports. The README documents the phase pipeline and security boundaries; sampled source confirms orchestration, MCP dispatch, database, review, and rendering details, but not every tool-to-storage call.

Main entry points: [`src/mulder/server/app.py`](https://github.com/calebevans/mulder/blob/main/src/mulder/server/app.py) (MCP server), [`src/mulder/cli.py`](https://github.com/calebevans/mulder/blob/main/src/mulder/cli.py) (CLI), [`src/mulder/db.py`](https://github.com/calebevans/mulder/blob/main/src/mulder/db.py) (Case database), [`src/mulder/orchestrator/runner.py`](https://github.com/calebevans/mulder/blob/main/src/mulder/orchestrator/runner.py) (Phase runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Investigation orchestration"]
  node_cli["CLI<br/>[cli.py]"]
  node_runner["Phase runner<br/>[runner.py]"]
  node_phases["Phase definitions<br/>[phases.py]"]
  node_gates["Quality gates<br/>[gates.py]"]
  node_session["Agent sessions<br/>[session.py]"]
end

subgraph group_mcp["MCP analysis tools"]
  node_extraction["Forensic extraction"]
  node_toolserver["MCP server<br/>[app.py]"]
  node_analysis["Cross-system analysis<br/>[correlator.py]"]
  node_attack["ATT&amp;CK mapping<br/>[attack.py]"]
  node_review["Alternative narrative<br/>[review.py]"]
end

subgraph group_evidence["Evidence and case state"]
  node_catalog["Evidence catalog<br/>[classifier.py]"]
  node_db[("Case database<br/>[db.py]")]
  node_models["Case data models<br/>[models.py]"]
end

subgraph group_outputs["Reports and audit"]
  node_audit["Audit trail<br/>[audit.py]"]
  node_report["Report renderer<br/>[renderer.py]"]
  node_ioc["IOC export<br/>[ioc_export.py]"]
  node_navigator["Navigator export<br/>[navigator.py]"]
end

node_investigator(("Investigator"))
node_agent(("Agent model"))
node_forensictools["Forensic utilities"]

node_investigator -->|"starts case"| node_cli
node_cli -->|"starts investigation"| node_runner
node_runner -->|"loads phases"| node_phases
node_runner -->|"runs phases"| node_session
node_runner -->|"checks phase results"| node_gates
node_session -->|"sends prompts"| node_agent
node_agent -->|"calls MCP tools"| node_toolserver
node_session -->|"configures MCP"| node_toolserver
node_toolserver -->|"classifies evidence"| node_catalog
node_toolserver -->|"dispatches tools"| node_extraction
node_extraction -->|"uses utilities"| node_forensictools
node_analysis -->|"queries time ranges"| node_db
node_review -->|"checks coverage"| node_db
node_toolserver -->|"records tool calls"| node_audit
node_toolserver -->|"validates and stores findings"| node_db
node_db -->|"returns case data"| node_models
node_cli -->|"renders reports"| node_report
node_cli -->|"exports IOCs"| node_ioc
node_cli -->|"exports ATT&amp;CK layers"| node_navigator
node_report -->|"reads findings"| node_db
node_report -->|"resolves evidence citations"| node_audit

click node_cli "https://github.com/calebevans/mulder/blob/main/src/mulder/cli.py"
click node_runner "https://github.com/calebevans/mulder/blob/main/src/mulder/orchestrator/runner.py"
click node_phases "https://github.com/calebevans/mulder/blob/main/src/mulder/orchestrator/phases.py"
click node_gates "https://github.com/calebevans/mulder/blob/main/src/mulder/orchestrator/gates.py"
click node_session "https://github.com/calebevans/mulder/blob/main/src/mulder/orchestrator/session.py"
click node_catalog "https://github.com/calebevans/mulder/blob/main/src/mulder/extractors/classifier.py"
click node_extraction "https://github.com/calebevans/mulder/tree/main/src/mulder/server/tools/extract"
click node_toolserver "https://github.com/calebevans/mulder/blob/main/src/mulder/server/app.py"
click node_analysis "https://github.com/calebevans/mulder/blob/main/src/mulder/index/correlator.py"
click node_attack "https://github.com/calebevans/mulder/blob/main/src/mulder/server/tools/attack.py"
click node_review "https://github.com/calebevans/mulder/blob/main/src/mulder/server/tools/review.py"
click node_db "https://github.com/calebevans/mulder/blob/main/src/mulder/db.py"
click node_models "https://github.com/calebevans/mulder/blob/main/src/mulder/models.py"
click node_audit "https://github.com/calebevans/mulder/blob/main/src/mulder/audit.py"
click node_report "https://github.com/calebevans/mulder/blob/main/src/mulder/report/renderer.py"
click node_ioc "https://github.com/calebevans/mulder/blob/main/src/mulder/report/ioc_export.py"
click node_navigator "https://github.com/calebevans/mulder/blob/main/src/mulder/report/navigator.py"

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_runner,node_phases,node_gates,node_session toneBlue
class node_extraction,node_toolserver,node_analysis,node_attack,node_review toneAmber
class node_catalog,node_db,node_models toneMint
class node_audit,node_report,node_ioc,node_navigator toneRose
class node_investigator,node_agent,node_forensictools toneIndigo
```

## Components

### Investigation orchestration

- [CLI](https://github.com/calebevans/mulder/blob/main/src/mulder/cli.py): `src/mulder/cli.py`
- [Phase runner](https://github.com/calebevans/mulder/blob/main/src/mulder/orchestrator/runner.py): `src/mulder/orchestrator/runner.py`
- [Phase definitions](https://github.com/calebevans/mulder/blob/main/src/mulder/orchestrator/phases.py): `src/mulder/orchestrator/phases.py`
- [Quality gates](https://github.com/calebevans/mulder/blob/main/src/mulder/orchestrator/gates.py): `src/mulder/orchestrator/gates.py`
- [Agent sessions](https://github.com/calebevans/mulder/blob/main/src/mulder/orchestrator/session.py): `src/mulder/orchestrator/session.py`

### MCP analysis tools

- [Forensic extraction](https://github.com/calebevans/mulder/tree/main/src/mulder/server/tools/extract): `src/mulder/server/tools/extract`
- [MCP server](https://github.com/calebevans/mulder/blob/main/src/mulder/server/app.py): `src/mulder/server/app.py`
- [Cross-system analysis](https://github.com/calebevans/mulder/blob/main/src/mulder/index/correlator.py): `src/mulder/index/correlator.py`
- [ATT&CK mapping](https://github.com/calebevans/mulder/blob/main/src/mulder/server/tools/attack.py): `src/mulder/server/tools/attack.py`
- [Alternative narrative](https://github.com/calebevans/mulder/blob/main/src/mulder/server/tools/review.py): `src/mulder/server/tools/review.py`

### Evidence and case state

- [Evidence catalog](https://github.com/calebevans/mulder/blob/main/src/mulder/extractors/classifier.py): `src/mulder/extractors/classifier.py`
- [Case database](https://github.com/calebevans/mulder/blob/main/src/mulder/db.py): `src/mulder/db.py`
- [Case data models](https://github.com/calebevans/mulder/blob/main/src/mulder/models.py): `src/mulder/models.py`

### Reports and audit

- [Audit trail](https://github.com/calebevans/mulder/blob/main/src/mulder/audit.py): `src/mulder/audit.py`
- [Report renderer](https://github.com/calebevans/mulder/blob/main/src/mulder/report/renderer.py): `src/mulder/report/renderer.py`
- [IOC export](https://github.com/calebevans/mulder/blob/main/src/mulder/report/ioc_export.py): `src/mulder/report/ioc_export.py`
- [Navigator export](https://github.com/calebevans/mulder/blob/main/src/mulder/report/navigator.py): `src/mulder/report/navigator.py`

### Other components

- **Investigator**
- **Agent model**
- **Forensic utilities**

## Connections

- Investigator → CLI: starts case
- CLI → Phase runner: starts investigation
- Phase runner → Phase definitions: loads phases
- Phase runner → Agent sessions: runs phases
- Phase runner → Quality gates: checks phase results
- Agent sessions → Agent model: sends prompts
- Agent model → MCP server: calls MCP tools
- Agent sessions → MCP server: configures MCP
- MCP server → Evidence catalog: classifies evidence
- MCP server → Forensic extraction: dispatches tools
- Forensic extraction → Forensic utilities: uses utilities
- Cross-system analysis → Case database: queries time ranges
- Alternative narrative → Case database: checks coverage
- MCP server → Audit trail: records tool calls
- MCP server → Case database: validates and stores findings
- Case database → Case data models: returns case data
- CLI → Report renderer: renders reports
- CLI → IOC export: exports IOCs
- CLI → Navigator export: exports ATT&CK layers
- Report renderer → Case database: reads findings
- Report renderer → Audit trail: resolves evidence citations