# martinzsir/investigation architecture

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

- Interactive diagram: https://gitdiagram.com/martinzsir/investigation
- Repository: https://github.com/martinzsir/investigation

## Overview

孙武侦查官 is a single-machine investigative analysis application: it ingests and standardizes case data, aligns people and organizations, generates and checks hypotheses, runs specialist analyses, and produces traceable clues for human review and disposition. Its documented skills cover scenario planning, bidirectional inventory, anomaly scanning, task division, and cross-source intelligence. DuckDB and Parquet form the primary storage path; Redis and LadybugDB are documented optional layers. The graph uses README claims where implementation excerpts were unavailable, so some subsystem links are intentionally omitted.

Main entry points: [`run_all.py`](https://github.com/martinzsir/investigation/blob/main/run_all.py) (Case Workflow), [`core/registry.py`](https://github.com/martinzsir/investigation/blob/main/core/registry.py) (Skill Registry), [`core/store.py`](https://github.com/martinzsir/investigation/blob/main/core/store.py) (Storage Interface), [`skills/xu_shi.py`](https://github.com/martinzsir/investigation/blob/main/skills/xu_shi.py) (Anomaly Scanning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Intake & Identity"]
  node_pipeline["Case Workflow<br/>[run_all.py]"]
  node_ingest["Data Adapters<br/>[data_ingest.py]"]
  node_entity["Entity Resolution"]
  node_org["Organization Alignment<br/>[entity.py]"]
end

subgraph group_analysis["Investigation Analysis"]
  node_hypotheses["Hypothesis Engine<br/>[hypotheses.py]"]
  node_sampling["Sampling Preflight<br/>[sampling.py]"]
  node_validate["Schema &amp; Redlines<br/>[validate.py]"]
  node_miaosuan["Scenario Planning<br/>[miaosuan.py]"]
  node_zhi_ji["Bidirectional Inventory<br/>[zhi_ji_zhi_bi.py]"]
  node_xu_shi["Anomaly Scanning<br/>[xu_shi.py]"]
  node_qi_zheng["Task Division<br/>[qi_zheng.py]"]
  node_yong_jian["Cross-Source Intelligence<br/>[yong_jian.py]"]
end

subgraph group_clues["Clues &amp; Review"]
  node_review["Merge Review<br/>[review.py]"]
  node_registry["Skill Registry<br/>[registry.py]"]
  node_bootstrap["Skill Adapters"]
  node_lineage["Clue Lineage<br/>[lineage.py]"]
  node_disposal["Clue Disposition<br/>[disposal.py]"]
end

subgraph group_storage["Storage &amp; Graph"]
  node_store["Storage Interface<br/>[store.py]"]
  node_duckdb[("DuckDB")]
  node_parquet[("Case Partitions")]
  node_redis[("Redis L1")]
  node_ladybug[("LadybugDB")]
  node_incremental["Partition Updates<br/>[incremental.py]"]
  node_export_graph["Graph Export<br/>[export_ladybug.py]"]
end

node_operator(("Investigator"))

node_operator -->|"starts workflow"| node_pipeline
node_pipeline -->|"ingests files"| node_ingest
node_ingest -->|"writes tables"| node_store
node_pipeline -->|"aligns entities"| node_entity
node_entity -->|"builds org alignment"| node_org
node_pipeline -->|"requests decisions"| node_review
node_pipeline -->|"preflights hypotheses"| node_sampling
node_pipeline -->|"builds hypotheses"| node_hypotheses
node_hypotheses -->|"checks constraints"| node_validate
node_pipeline -->|"runs planning"| node_miaosuan
node_pipeline -->|"runs inventory"| node_zhi_ji
node_pipeline -->|"runs scans"| node_xu_shi
node_pipeline -->|"runs task division"| node_qi_zheng
node_pipeline -->|"runs cross-check"| node_yong_jian
node_xu_shi -->|"queries partitions"| node_parquet
node_xu_shi -->|"executes queries"| node_store
node_store -->|"reads and writes"| node_duckdb
node_bootstrap -->|"registers handlers"| node_registry
node_registry -->|"dispatches skill"| node_xu_shi
node_registry -->|"dispatches skill"| node_qi_zheng
node_registry -->|"dispatches skill"| node_yong_jian
node_registry -->|"returns traced clues"| node_lineage
node_pipeline -->|"merges and prioritizes"| node_lineage
node_lineage -->|"tracks disposition"| node_disposal
node_disposal -->|"persists status"| node_store
node_incremental -->|"updates aggregates"| node_duckdb
node_export_graph -.->|"reads edge data"| node_duckdb
node_export_graph -.->|"materializes edges"| node_ladybug
node_store -.->|"optional hot cache"| node_redis

click node_pipeline "https://github.com/martinzsir/investigation/blob/main/run_all.py"
click node_ingest "https://github.com/martinzsir/investigation/blob/main/data_ingest.py"
click node_entity "https://github.com/martinzsir/investigation/blob/main/entity_resolution.py"
click node_org "https://github.com/martinzsir/investigation/blob/main/core/entity.py"
click node_review "https://github.com/martinzsir/investigation/blob/main/core/review.py"
click node_store "https://github.com/martinzsir/investigation/blob/main/core/store.py"
click node_parquet "https://github.com/martinzsir/investigation/tree/main/data"
click node_hypotheses "https://github.com/martinzsir/investigation/blob/main/core/hypotheses.py"
click node_sampling "https://github.com/martinzsir/investigation/blob/main/core/sampling.py"
click node_validate "https://github.com/martinzsir/investigation/blob/main/core/validate.py"
click node_miaosuan "https://github.com/martinzsir/investigation/blob/main/skills/miaosuan.py"
click node_zhi_ji "https://github.com/martinzsir/investigation/blob/main/skills/zhi_ji_zhi_bi.py"
click node_xu_shi "https://github.com/martinzsir/investigation/blob/main/skills/xu_shi.py"
click node_qi_zheng "https://github.com/martinzsir/investigation/blob/main/skills/qi_zheng.py"
click node_yong_jian "https://github.com/martinzsir/investigation/blob/main/skills/yong_jian.py"
click node_registry "https://github.com/martinzsir/investigation/blob/main/core/registry.py"
click node_bootstrap "https://github.com/martinzsir/investigation/blob/main/skills/registry_bootstrap.py"
click node_lineage "https://github.com/martinzsir/investigation/blob/main/core/lineage.py"
click node_disposal "https://github.com/martinzsir/investigation/blob/main/core/disposal.py"
click node_incremental "https://github.com/martinzsir/investigation/blob/main/scripts/incremental.py"
click node_export_graph "https://github.com/martinzsir/investigation/blob/main/scripts/export_ladybug.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_pipeline,node_ingest,node_entity,node_org toneBlue
class node_hypotheses,node_sampling,node_validate,node_miaosuan,node_zhi_ji,node_xu_shi,node_qi_zheng,node_yong_jian toneAmber
class node_review,node_registry,node_bootstrap,node_lineage,node_disposal toneMint
class node_store,node_duckdb,node_parquet,node_redis,node_ladybug,node_incremental,node_export_graph toneRose
class node_operator toneIndigo
```

## Components

### Intake & Identity

- [Case Workflow](https://github.com/martinzsir/investigation/blob/main/run_all.py): `run_all.py`
- [Data Adapters](https://github.com/martinzsir/investigation/blob/main/data_ingest.py): `data_ingest.py`
- [Entity Resolution](https://github.com/martinzsir/investigation/blob/main/entity_resolution.py): `entity_resolution.py`
- [Organization Alignment](https://github.com/martinzsir/investigation/blob/main/core/entity.py): `core/entity.py`

### Investigation Analysis

- [Hypothesis Engine](https://github.com/martinzsir/investigation/blob/main/core/hypotheses.py): `core/hypotheses.py`
- [Sampling Preflight](https://github.com/martinzsir/investigation/blob/main/core/sampling.py): `core/sampling.py`
- [Schema & Redlines](https://github.com/martinzsir/investigation/blob/main/core/validate.py): `core/validate.py`
- [Scenario Planning](https://github.com/martinzsir/investigation/blob/main/skills/miaosuan.py): `skills/miaosuan.py`
- [Bidirectional Inventory](https://github.com/martinzsir/investigation/blob/main/skills/zhi_ji_zhi_bi.py): `skills/zhi_ji_zhi_bi.py`
- [Anomaly Scanning](https://github.com/martinzsir/investigation/blob/main/skills/xu_shi.py): `skills/xu_shi.py`
- [Task Division](https://github.com/martinzsir/investigation/blob/main/skills/qi_zheng.py): `skills/qi_zheng.py`
- [Cross-Source Intelligence](https://github.com/martinzsir/investigation/blob/main/skills/yong_jian.py): `skills/yong_jian.py`

### Clues & Review

- [Merge Review](https://github.com/martinzsir/investigation/blob/main/core/review.py): `core/review.py`
- [Skill Registry](https://github.com/martinzsir/investigation/blob/main/core/registry.py): `core/registry.py`
- [Skill Adapters](https://github.com/martinzsir/investigation/blob/main/skills/registry_bootstrap.py): `skills/registry_bootstrap.py`
- [Clue Lineage](https://github.com/martinzsir/investigation/blob/main/core/lineage.py): `core/lineage.py`
- [Clue Disposition](https://github.com/martinzsir/investigation/blob/main/core/disposal.py): `core/disposal.py`

### Storage & Graph

- [Storage Interface](https://github.com/martinzsir/investigation/blob/main/core/store.py): `core/store.py`
- **DuckDB**
- [Case Partitions](https://github.com/martinzsir/investigation/tree/main/data): `data`
- **Redis L1**
- **LadybugDB**
- [Partition Updates](https://github.com/martinzsir/investigation/blob/main/scripts/incremental.py): `scripts/incremental.py`
- [Graph Export](https://github.com/martinzsir/investigation/blob/main/scripts/export_ladybug.py): `scripts/export_ladybug.py`

### Other components

- **Investigator**

## Connections

- Investigator → Case Workflow: starts workflow
- Case Workflow → Data Adapters: ingests files
- Data Adapters → Storage Interface: writes tables
- Case Workflow → Entity Resolution: aligns entities
- Entity Resolution → Organization Alignment: builds org alignment
- Case Workflow → Merge Review: requests decisions
- Case Workflow → Sampling Preflight: preflights hypotheses
- Case Workflow → Hypothesis Engine: builds hypotheses
- Hypothesis Engine → Schema & Redlines: checks constraints
- Case Workflow → Scenario Planning: runs planning
- Case Workflow → Bidirectional Inventory: runs inventory
- Case Workflow → Anomaly Scanning: runs scans
- Case Workflow → Task Division: runs task division
- Case Workflow → Cross-Source Intelligence: runs cross-check
- Anomaly Scanning → Case Partitions: queries partitions
- Anomaly Scanning → Storage Interface: executes queries
- Storage Interface → DuckDB: reads and writes
- Skill Adapters → Skill Registry: registers handlers
- Skill Registry → Anomaly Scanning: dispatches skill
- Skill Registry → Task Division: dispatches skill
- Skill Registry → Cross-Source Intelligence: dispatches skill
- Skill Registry → Clue Lineage: returns traced clues
- Case Workflow → Clue Lineage: merges and prioritizes
- Clue Lineage → Clue Disposition: tracks disposition
- Clue Disposition → Storage Interface: persists status
- Partition Updates → DuckDB: updates aggregates
- Graph Export → DuckDB: reads edge data
- Graph Export → LadybugDB: materializes edges
- Storage Interface → Redis L1: optional hot cache