# shroudb/cargo-shroudb architecture

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

- Interactive diagram: https://gitdiagram.com/shroudb/cargo-shroudb
- Repository: https://github.com/shroudb/cargo-shroudb

## Overview

cargo-shroudb is a Cargo subcommand that discovers ShrouDB dependencies and manages the corresponding agent-instruction section in a Rust project. The main workflow is `init-agents`: inspect dependencies and lockfile versions, locate crate sources and their AGENTS.md files, then generate or update the project reference, optionally copying instructions locally. Separate commands check whether that reference is stale and remove generated content. Runtime details come from the README and partial `src/main.rs` excerpts; internal links not established by those excerpts are omitted.

Main entry points: [`src/main.rs`](https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs) (Init agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command handling"]
  node_entry["Command dispatch<br/>[main.rs]"]
  node_init["Init agents<br/>[main.rs]"]
  node_check["Check agents<br/>[main.rs]"]
  node_clean["Clean agents<br/>[main.rs]"]
end

subgraph group_discovery["Dependency discovery"]
  node_manifest["Cargo.toml"]
  node_lockfile["Cargo.lock"]
  node_scan["Find dependencies<br/>[main.rs]"]
  node_versions["Resolve versions<br/>[main.rs]"]
  node_sources["Locate crate sources<br/>[main.rs]"]
  node_crate_instructions["Crate AGENTS.md"]
end

subgraph group_agents["Agent reference management"]
  node_reference["Project AGENTS.md"]
  node_generate["Generate section<br/>[main.rs]"]
  node_copy["Copy local instructions<br/>[main.rs]"]
  node_compare["Compare dependencies<br/>[main.rs]"]
  node_remove["Remove generated content<br/>[main.rs]"]
  node_local_agents["Local agent copies"]
end

node_user(("CLI user"))
node_cargo_sources[("Cargo source caches")]

node_user -->|"runs command"| node_entry
node_entry -->|"dispatches"| node_init
node_entry -->|"dispatches"| node_check
node_entry -->|"dispatches"| node_clean
node_init -->|"discovers dependencies"| node_scan
node_scan -->|"reads"| node_manifest
node_init -->|"resolves versions"| node_versions
node_versions -->|"reads"| node_lockfile
node_init -->|"locates sources"| node_sources
node_sources -->|"searches"| node_cargo_sources
node_sources -->|"checks for"| node_crate_instructions
node_init -->|"builds reference"| node_generate
node_generate -->|"writes or updates"| node_reference
node_init -.->|"optionally copies"| node_copy
node_copy -.->|"writes"| node_local_agents
node_check -->|"discovers current dependencies"| node_scan
node_check -->|"resolves current versions"| node_versions
node_check -->|"reads"| node_reference
node_check -->|"checks freshness"| node_compare
node_compare -->|"parses listed crates"| node_reference
node_clean -->|"removes marked section"| node_reference
node_clean -->|"removes directory"| node_local_agents

click node_entry "https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs"
click node_init "https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs"
click node_check "https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs"
click node_clean "https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs"
click node_scan "https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs"
click node_versions "https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs"
click node_sources "https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs"
click node_generate "https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs"
click node_copy "https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs"
click node_compare "https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs"
click node_remove "https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs"

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_entry,node_init,node_check,node_clean,node_user toneBlue
class node_manifest,node_lockfile,node_scan,node_versions,node_sources,node_crate_instructions,node_cargo_sources toneAmber
class node_reference,node_generate,node_copy,node_compare,node_remove,node_local_agents toneMint
```

## Components

### Command handling

- [Command dispatch](https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs): `src/main.rs`
- [Init agents](https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs): `src/main.rs`
- [Check agents](https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs): `src/main.rs`
- [Clean agents](https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs): `src/main.rs`

### Dependency discovery

- **Cargo.toml**
- **Cargo.lock**
- [Find dependencies](https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs): `src/main.rs`
- [Resolve versions](https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs): `src/main.rs`
- [Locate crate sources](https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs): `src/main.rs`
- **Crate AGENTS.md**

### Agent reference management

- **Project AGENTS.md**
- [Generate section](https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs): `src/main.rs`
- [Copy local instructions](https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs): `src/main.rs`
- [Compare dependencies](https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs): `src/main.rs`
- [Remove generated content](https://github.com/shroudb/cargo-shroudb/blob/main/src/main.rs): `src/main.rs`
- **Local agent copies**

### Other components

- **CLI user**
- **Cargo source caches**

## Connections

- CLI user → Command dispatch: runs command
- Command dispatch → Init agents: dispatches
- Command dispatch → Check agents: dispatches
- Command dispatch → Clean agents: dispatches
- Init agents → Find dependencies: discovers dependencies
- Find dependencies → Cargo.toml: reads
- Init agents → Resolve versions: resolves versions
- Resolve versions → Cargo.lock: reads
- Init agents → Locate crate sources: locates sources
- Locate crate sources → Cargo source caches: searches
- Locate crate sources → Crate AGENTS.md: checks for
- Init agents → Generate section: builds reference
- Generate section → Project AGENTS.md: writes or updates
- Init agents → Copy local instructions: optionally copies
- Copy local instructions → Local agent copies: writes
- Check agents → Find dependencies: discovers current dependencies
- Check agents → Resolve versions: resolves current versions
- Check agents → Project AGENTS.md: reads
- Check agents → Compare dependencies: checks freshness
- Compare dependencies → Project AGENTS.md: parses listed crates
- Clean agents → Project AGENTS.md: removes marked section
- Clean agents → Local agent copies: removes directory