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.
| 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) |
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.
codetwin-<role>. The bin keeps the
bare name codetwin because that is what users install.codetwin_ir, etc.) — Rust requirement.Cargo.toml
via [workspace.package]. Releases bump every crate together.[workspace.dependencies] at the root,
inherited by members with { workspace = true }. Adding a new external
dependency is a workspace-level decision (see AGENTS.md).[workspace.lints] and inherited with [lints] workspace = true.
CodeTwin forbids unsafe code and enables the template’s Rust and Clippy warning policies.[workspace.dependencies] with path =
"...". Members reference them with { workspace = true }.codetwin is published. Every other crate sets
publish = false until we have a reason to expose it.cargo xtask scaffold crate <semantic-name> --dry-run.IR extraction is complete. Further decomposition is deferred until ownership boundaries are justified; the earlier proposed moves were:
ir/ → codetwin-irconfig/ → codetwin-configdrivers/ → codetwin-driversrender/, layouts/ → codetwin-renderpipeline/, snapshot/, diff/, watch/ → codetwin-pipelinecli/ → codetwin-cliutil/ → folded into whichever crate uses it (no cross-cutting util crate)When codetwin-legacy is empty, delete it and switch the bin to depend on
codetwin-cli. Track in ROADMAP.md Phase 0.