# nidusvespae/yingzi architecture

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

- Interactive diagram: https://gitdiagram.com/nidusvespae/yingzi
- Repository: https://github.com/nidusvespae/yingzi

## Overview

影子 is a local, self-only data-broker exposure tracker for an Obsidian vault. Its weekly workflow loads private identifiers and configuration, seeds the Roster if needed, reads and evaluates the Roster, then writes a Footprint while carrying forward history and refusing writes containing identifiers. The catalog supplies broker and FCRA tracking rules; the report also includes manual checks and an explainer note. Mentions are explicitly disabled, even if a search key is present. Edges reflect the runner and core excerpts or README; unsampled details are not inferred.

Main entry points: [`yingzi_run.py`](https://github.com/nidusvespae/yingzi/blob/main/yingzi_run.py) (Run orchestrator), [`yingzi.py`](https://github.com/nidusvespae/yingzi/blob/main/yingzi.py) (Roster parsing), [`catalog.py`](https://github.com/nidusvespae/yingzi/blob/main/catalog.py) (Broker catalog), [`mentions.py`](https://github.com/nidusvespae/yingzi/blob/main/mentions.py) (Disabled mentions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and catalog"]
  node_config["Local config"]
  node_secrets["Secrets file"]
  node_catalog["Broker catalog<br/>[catalog.py]"]
end

subgraph group_core["Tracking logic"]
  node_roster["Roster parsing<br/>[yingzi.py]"]
  node_evaluation["Status evaluation<br/>[yingzi.py]"]
  node_leakwall["Identifier leak wall<br/>[yingzi.py]"]
  node_report["Footprint rendering<br/>[yingzi.py]"]
  node_explainer["Explainer rendering<br/>[yingzi.py]"]
  node_mentions["Disabled mentions<br/>[mentions.py]"]
end

subgraph group_runner["Weekly runner"]
  node_runner["Run orchestrator<br/>[yingzi_run.py]"]
end

subgraph group_outputs["Vault and state"]
  node_vault["Obsidian vault"]
  node_history[("Run history")]
end

node_operator(("Vault owner"))
node_gate["Optional write gate"]

node_operator -->|"configures"| node_config
node_operator -->|"edits"| node_roster
node_runner -->|"loads"| node_config
node_runner -->|"builds patterns"| node_leakwall
node_runner -->|"seeds or parses"| node_roster
node_roster -->|"provides statuses"| node_evaluation
node_evaluation -->|"uses rules"| node_catalog
node_runner -->|"checks status"| node_mentions
node_runner -->|"checks key"| node_secrets
node_runner -->|"requests rendering"| node_report
node_report -->|"uses entries"| node_catalog
node_runner -->|"requests rendering"| node_explainer
node_runner -->|"reads roster"| node_vault
node_runner -->|"writes notes"| node_vault
node_runner -->|"loads and saves"| node_history
node_runner -->|"checks writes"| node_leakwall
node_runner -->|"dispatches writes"| node_gate

click node_catalog "https://github.com/nidusvespae/yingzi/blob/main/catalog.py"
click node_runner "https://github.com/nidusvespae/yingzi/blob/main/yingzi_run.py"
click node_roster "https://github.com/nidusvespae/yingzi/blob/main/yingzi.py"
click node_evaluation "https://github.com/nidusvespae/yingzi/blob/main/yingzi.py"
click node_leakwall "https://github.com/nidusvespae/yingzi/blob/main/yingzi.py"
click node_report "https://github.com/nidusvespae/yingzi/blob/main/yingzi.py"
click node_explainer "https://github.com/nidusvespae/yingzi/blob/main/yingzi.py"
click node_mentions "https://github.com/nidusvespae/yingzi/blob/main/mentions.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_config,node_secrets,node_catalog toneBlue
class node_roster,node_evaluation,node_leakwall,node_report,node_explainer,node_mentions toneAmber
class node_runner toneMint
class node_vault,node_history toneRose
class node_operator,node_gate toneIndigo
```

## Components

### Inputs and catalog

- **Local config**
- **Secrets file**
- [Broker catalog](https://github.com/nidusvespae/yingzi/blob/main/catalog.py): `catalog.py`

### Tracking logic

- [Roster parsing](https://github.com/nidusvespae/yingzi/blob/main/yingzi.py): `yingzi.py`
- [Status evaluation](https://github.com/nidusvespae/yingzi/blob/main/yingzi.py): `yingzi.py`
- [Identifier leak wall](https://github.com/nidusvespae/yingzi/blob/main/yingzi.py): `yingzi.py`
- [Footprint rendering](https://github.com/nidusvespae/yingzi/blob/main/yingzi.py): `yingzi.py`
- [Explainer rendering](https://github.com/nidusvespae/yingzi/blob/main/yingzi.py): `yingzi.py`
- [Disabled mentions](https://github.com/nidusvespae/yingzi/blob/main/mentions.py): `mentions.py`

### Weekly runner

- [Run orchestrator](https://github.com/nidusvespae/yingzi/blob/main/yingzi_run.py): `yingzi_run.py`

### Vault and state

- **Obsidian vault**
- **Run history**

### Other components

- **Vault owner**
- **Optional write gate**

## Connections

- Vault owner → Local config: configures (evidence: `README.md`)
- Vault owner → Roster parsing: edits (evidence: `README.md`)
- Run orchestrator → Local config: loads (evidence: `yingzi_run.py`)
- Run orchestrator → Identifier leak wall: builds patterns (evidence: `yingzi_run.py`)
- Run orchestrator → Roster parsing: seeds or parses (evidence: `yingzi_run.py`)
- Roster parsing → Status evaluation: provides statuses (evidence: `yingzi_run.py`)
- Status evaluation → Broker catalog: uses rules (evidence: `yingzi.py`)
- Run orchestrator → Disabled mentions: checks status (evidence: `yingzi_run.py`)
- Run orchestrator → Secrets file: checks key (evidence: `yingzi_run.py`)
- Run orchestrator → Footprint rendering: requests rendering (evidence: `yingzi_run.py`)
- Footprint rendering → Broker catalog: uses entries (evidence: `yingzi.py`)
- Run orchestrator → Explainer rendering: requests rendering (evidence: `yingzi_run.py`)
- Run orchestrator → Obsidian vault: reads roster (evidence: `yingzi_run.py`)
- Run orchestrator → Obsidian vault: writes notes (evidence: `yingzi_run.py`)
- Run orchestrator → Run history: loads and saves (evidence: `yingzi_run.py`)
- Run orchestrator → Identifier leak wall: checks writes (evidence: `yingzi_run.py`)
- Run orchestrator → Optional write gate: dispatches writes (evidence: `yingzi_run.py`)
