codetwin

Crates

CodeTwin is organised as a Cargo workspace. Each crate has one job and a narrow public surface. New crates are added when a real seam appears (two adapters, not one).

Private development automation lives at tools/xtask, outside the product crates. Its commands run checks and scaffold roadmap-approved capabilities; it is not part of the shipped binary.

Five successor crates (cli, pipeline, render, drivers, config) are scaffolds. Their roles below describe proposed ownership; current legacy implementations remain in codetwin-legacy. New workspace analysis and visualization live in codetwin.

Index

Crate Role Depends on
codetwin Binary and library: CLI, Rust workspace inventory, Markdown visualization. codetwin-ir, codetwin-legacy
codetwin-cli clap-derived CLI surface and subcommand dispatch. codetwin-config, codetwin-pipeline
codetwin-pipeline Orchestration: discover → parse → merge → render → write. Owns snapshot, diff, watch. codetwin-ir, codetwin-config, codetwin-drivers, codetwin-render
codetwin-render Markdown / Mermaid builders and the Layout trait + built-in layouts. codetwin-ir
codetwin-drivers Driver trait, auto-detection registry, and per-language tree-sitter drivers. codetwin-ir
codetwin-config codetwin.toml schema + loader + override merging. (leaf)
codetwin-ir Intermediate representation: CodeModel, Module, Symbol, Edge. (leaf)
codetwin-legacy Transitional. Holds the pre-workspace monolith while modules migrate out. (everything the monolith did)

Dependency DAG

codetwin (binary and library)
  ├── codetwin-ir
  └── codetwin-legacy
       └── codetwin-ir

This is the implemented product chain. For all declared workspace dependencies, including scaffolds and development automation, see the generated overview.

Edges only point downward. A leaf crate must never depend on a higher-level one. Adding an upward edge needs an explicit ADR.

Conventions

Adding a new crate

  1. Confirm the seam is real (two adapters, not one — see AGENTS.md).
  2. Preview cargo xtask scaffold crate <semantic-name> --dry-run.
  3. Run the scaffold with the required visibility; review its manifest and source changes.
  4. Add a row to the table above.
  5. Update the dependency DAG diagram if a new edge appears.

Phase 0 migration status

IR extraction is complete. Further decomposition is deferred until ownership boundaries are justified; the earlier proposed moves were:

When codetwin-legacy is empty, delete it and switch the bin to depend on codetwin-cli. Track in ROADMAP.md Phase 0.