# Design Rationale

## Why pccx-lab is one repo, not five

In the initial design, we considered a 5-repo structure (simulator / frontend / uvm-bridge / ai / common). However, this was rejected for the following reasons:

1. **Development Speed**: The overhead of synchronizing changes and managing versions across multiple repositories is massive.
2. **Single Purpose**: All modules ultimately work closely together towards the single goal of "pccx profiling".

## Module Boundary Rules

To prevent the downside of a monorepo (spaghetti code), we enforce strict module boundaries.  Phase 1 split the original monolithic `core/` into nine focused crates under `crates/` plus a top-level `ui/`; dependency edges are unidirectional and `pccx-core` is the single sink of the workspace graph (see `docs/design/phase1_crate_split.md` § 3 for the full diagram).

- `pccx-core` (`crates/core/`): pure Rust core — .pccx format, trace parsing, hardware model, roofline, bottleneck detection, VCD / chrome-trace writers, step-snapshot IPC, Vivado timing ingest.  Depends on no other workspace crate.  Strictly forbids importing UI frameworks.
- `pccx-reports` (`crates/reports/`): Markdown / HTML / PDF report rendering.  Depends on `pccx-core`.
- `pccx-verification` (`crates/verification/`): golden-diff + robust reader gates used by CI and pccx-ide.  Depends on `pccx-core`.
- `pccx-authoring` (`crates/authoring/`): ISA and API TOML compilers.  Depends on `pccx-core`.
- `pccx-evolve` (`crates/evolve/`): speculative-decoding primitives for EAGLE-family strategies; future home of the Phase 5 DSE + surrogate + PRM loop.  Depends on `pccx-core` and `pccx-verification`.
- `pccx-lsp` (`crates/lsp/`): Phase 2 IntelliSense façade — sync and async provider traits, multiplexers, `NoopBackend`, `BlockingBridge`, `LspSubprocess`.  Depends on `pccx-core`.
- `pccx-remote` (`crates/remote/`): Phase 3 backend-daemon scaffold (WireGuard / OIDC / RBAC land later).  Depends on `pccx-core`.
- `pccx-uvm-bridge` (`crates/uvm_bridge/`): DPI-C / FFI boundary between SystemVerilog/UVM and `pccx-core`.  Depends on `pccx-core`.
- `pccx-ai-copilot` (`crates/ai_copilot/`): LLM invocation wrapper.  Depends only on `pccx-core`'s trace surface (JSON or typed).
- `pccx-ide` (`ui/src-tauri/`): Tauri shell that consumes `pccx-core`, `pccx-reports`, and `pccx-ai-copilot`.
- `ui/` (non-Cargo): React + Vite frontend; reads from `pccx-ide` over Tauri IPC only.

No crate depends on `pccx-ide` or `pccx-remote` — both are terminal binaries.  The React tree is not a Cargo member; it is outside the workspace graph by design.

## Conditions for Future Separation

If a specific crate (e.g. `pccx-core` or `pccx-verification`) becomes generic enough to be used independently outside pccx-lab, we will publish it to crates.io or extract it into its own repository.  The Phase 1 split was done with this in mind: every non-core crate already exposes an unstable trait surface (`ReportFormat`, `VerificationGate`, `IsaCompiler`, `ApiCompiler`, `CompletionProvider`, etc.), so "carve out" is a follow-on release task rather than an architectural refactor.