| 1 | # CascadeIDE current architecture (v1) |
| 2 | |
| 3 | This document is the **single entry point** for **how things are structured today** (not “why”). |
| 4 | Decision context and alternatives — in **ADR**: [../adr/README.md](../adr/README.md). |
| 5 | Policy and “where to look” — [../architecture-policy.md](../architecture-policy.md). |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## 1. System model (one screen) |
| 10 | |
| 11 | CascadeIDE is a desktop IDE (Avalonia + MVVM) where **cockpit semantics** (PFD / Forward / MFD) define the attention structure, and MCP makes the IDE agent-operable. |
| 12 | |
| 13 | - **PFD**: primary attention zone, short situational summary and “command” indicators. |
| 14 | - **Forward**: work zone (editor/docs), main action stream. |
| 15 | - **MFD**: secondary loop — **long streams** (terminal/build/Git/…): **pages** on a stack. |
| 16 | |
| 17 | Layout reference for the main window and region names for MCP: |
| 18 | - [../ui-ux/cascade-ide-ui-layout-v1.md](../ui-ux/cascade-ide-ui-layout-v1.md) |
| 19 | |
| 20 | --- |
| 21 | |
| 22 | ## 2. Layers and responsibility boundaries |
| 23 | |
| 24 | Normative layers and “what lives where”: |
| 25 | - **ADR 0006**: layers, feature slices, role of `MainWindowViewModel` — [../adr/0006-presentation-layers-and-feature-slices.md](../adr/0006-presentation-layers-and-feature-slices.md) |
| 26 | - **ADR 0102**: DAL (external adapter boundary) — [../adr/0102-data-acquisition-layer-boundary-and-contract.md](../adr/0102-data-acquisition-layer-boundary-and-contract.md) |
| 27 | - **ADR 0097**: CCU (raw input → DTO/snapshot fold) — [../adr/0097-cockpit-compute-units-transport-to-channel-dto.md](../adr/0097-cockpit-compute-units-transport-to-channel-dto.md) |
| 28 | - **ADR 0099**: IDE DataBus (typed events) — [../adr/0099-ide-databus-typed-events-and-projections.md](../adr/0099-ide-databus-typed-events-and-projections.md) |
| 29 | - **ADR 0036**: CDS → compositor → surface (cockpit as meaning domain) — [../adr/0036-cds-channel-compositor-surface-pipeline.md](../adr/0036-cds-channel-compositor-surface-pipeline.md) |
| 30 | - **ADR 0079**: IDS (IDE overlays) as separate domain from CDS — [../adr/0079-ide-display-system-ids-overlay-pipeline.md](../adr/0079-ide-display-system-ids-overlay-pipeline.md) |
| 31 | |
| 32 | Practical mental model (top to bottom): |
| 33 | |
| 34 | - **UI (Views)**: `Views/*.axaml` and related `*.axaml.cs`. Keep simple: layout, bindings, region naming. |
| 35 | - **VM (ViewModels)**: state composition, commands, links between attention zones. |
| 36 | - **Application / orchestration**: use-case coordination inside a feature (typically `Features/<Feature>/Application/*`). |
| 37 | - **DAL**: inbound/outbound to the outside world (processes, git, LSP, MCP clients, file system). |
| 38 | - **Transport / bus / batching**: event/line delivery to UI (bounded, backpressure). |
| 39 | - **CCU**: fold events/raw input into DTO suitable for UI and observability. |
| 40 | |
| 41 | --- |
| 42 | |
| 43 | ## 3. “Flight” UI architecture (fact, not concept) |
| 44 | |
| 45 | The main window is **three columns** PFD | Forward | MFD. Long streams (Terminal/Build/Git/…) live as **MFD pages**, not a full-width bottom panel. |
| 46 | |
| 47 | Detail: |
| 48 | - [../ui-ux/cascade-ide-ui-layout-v1.md](../ui-ux/cascade-ide-ui-layout-v1.md) |
| 49 | - Concept → code map (what is historical vs current): [../ui-ux/concept-to-implementation-map-v1.md](../ui-ux/concept-to-implementation-map-v1.md) |
| 50 | |
| 51 | Key MFD elements (current names): |
| 52 | - `MfdShellView` + `MfdShellPageStack` |
| 53 | - stack host region (snapshots/theme/contracts): `MfdContourStackHost` |
| 54 | |
| 55 | --- |
| 56 | |
| 57 | ## 4. MCP: IDE as tool server |
| 58 | |
| 59 | Contract and protocol: |
| 60 | - [../../MCP-PROTOCOL.md](../../MCP-PROTOCOL.md) |
| 61 | - **ADR 0008** (contracts and testable infrastructure): [../adr/0008-mcp-contracts-and-testable-infrastructure.md](../adr/0008-mcp-contracts-and-testable-infrastructure.md) |
| 62 | - **ADR 0052** (contract CLI and snapshot tests): [../adr/0052-agent-contract-cli-and-snapshot-tests.md](../adr/0052-agent-contract-cli-and-snapshot-tests.md) |
| 63 | |
| 64 | Remember: |
| 65 | - MCP targets **observability** (snapshots, diagnostics) and **control** (commands), not “secret” APIs. |
| 66 | - UI region keys exposed to the agent should be stable and documented (see layout doc above). |
| 67 | |
| 68 | --- |
| 69 | |
| 70 | ## 5. Hybrid index and code navigation (brief) |
| 71 | |
| 72 | - **Hybrid index (FTS + vec)** as local context DB: |
| 73 | [../adr/0105-hybrid-codebase-index-for-csharp-web.md](../adr/0105-hybrid-codebase-index-for-csharp-web.md) (Accepted · Implemented) |
| 74 | [../adr/0106-hybrid-codebase-index-cascadeide-integration-and-semantic-map.md](../adr/0106-hybrid-codebase-index-cascadeide-integration-and-semantic-map.md) (Proposed) |
| 75 | - Navigation MCP (`get_code_navigation_context`) and presets: |
| 76 | [../adr/0039-workspace-navigation-affordances.md](../adr/0039-workspace-navigation-affordances.md) |
| 77 | |
| 78 | --- |
| 79 | |
| 80 | ## 6. “Where to look in code” (anchors) |
| 81 | |
| 82 | Not a full list — a “first ten” for orientation. |
| 83 | |
| 84 | - **UI layout / regions**: `Views/MainWindow.axaml`, `Views/MfdShellView.axaml` |
| 85 | - **Main window VM**: `ViewModels/MainWindowViewModel.*.cs` (partials) |
| 86 | - **Hybrid Index orchestration**: `Features/HybridIndex/Application/*` |
| 87 | - **CCU / cockpit channels**: `Cockpit/ComputingUnits/*`, `Cockpit/Channels/*`, `Cockpit/Cds/*`, `Cockpit/Composition/*`, `Cockpit/Surface/*` |
| 88 | - **MCP tool catalog / protocol docs**: `Services/*` (see ADR 0008 and `MCP-PROTOCOL.md`) |
| 89 | |
| 90 | For layer boundaries, Roslyn analyzers help: |
| 91 | - [../../../CascadeIDE.ArchitectureAnalyzers/README.md](../../../CascadeIDE.ArchitectureAnalyzers/README.md) |
| 92 | |
| 93 | --- |
| 94 | |
| 95 | ## 7. What to treat as historical (do not confuse with current) |
| 96 | |
| 97 | The repo has docs and concepts describing older layouts (e.g. full-width “bottom panel”). |
| 98 | See explicit “old topology” notes in: |
| 99 | - [../ui-ux/cascade-ide-ui-layout-v1.md](../ui-ux/cascade-ide-ui-layout-v1.md) |
| 100 | - [../../architecture-migration.md](../../architecture-migration.md) |
| 101 | |
| 102 | --- |
| 103 | |
| 104 | ## 8. How to update this document |
| 105 | |
| 106 | Update when at least one of these changes: |
| 107 | - attention zone topology (PFD/Forward/MFD), key regions and their names; |
| 108 | - layer boundaries (DAL/CCU/DataBus/IDS/CDS) or the main “data path”; |
| 109 | - MCP contract (new tools, key/format changes). |
| 110 | |
| 111 | Version: **v1** (current slice). |
| 112 | |