| 1 | # ADR map: how to read CascadeIDE architecture (v1) |
| 2 | |
| 3 | This document answers: **which ADRs to read to understand the system** — by topic and by role. |
| 4 | It does not replace the ADR index: [../adr/README.md](../adr/README.md). |
| 5 | Current architecture “as is” — [current-architecture-v1.md](current-architecture-v1.md). |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## 1. Where to start (fast route) |
| 10 | |
| 11 | - **Layers and boundaries**: [`0006`](../adr/0006-presentation-layers-and-feature-slices.md) |
| 12 | - **Data flow and cockpit (CDS)**: [`0036`](../adr/0036-cds-channel-compositor-surface-pipeline.md) |
| 13 | - **IDE overlay domain (IDS), separate from CDS**: [`0079`](../adr/0079-ide-display-system-ids-overlay-pipeline.md) |
| 14 | - **MCP contracts and testable infrastructure**: [`0008`](../adr/0008-mcp-contracts-and-testable-infrastructure.md) |
| 15 | - **Code navigation / navigation MCP**: [`0039`](../adr/0039-workspace-navigation-affordances.md) |
| 16 | |
| 17 | If you are reading for “how Flight UI is laid out today”, start with the layout doc, not ADR: |
| 18 | - [../ui-ux/cascade-ide-ui-layout-v1.md](../ui-ux/cascade-ide-ui-layout-v1.md) |
| 19 | |
| 20 | --- |
| 21 | |
| 22 | ## 2. UI and attention model (PFD / Forward / MFD) |
| 23 | |
| 24 | - **Attention model and PFD/MFD terminology**: [`0021`](../adr/0021-pfd-mfd-cockpit-attention-model.md) *(Proposed, but sets the language)* |
| 25 | - **Layout invariants and `presentation` authority**: [`0046`](../adr/0046-presentation-layout-authority-and-cockpit-invariants.md) *(Accepted · Implemented)* |
| 26 | - **Multi-window and surfaces**: [`0017`](../adr/0017-multi-window-workspace-and-agent-surfaces.md) *(Accepted · Implemented)* |
| 27 | - **Remote operator surface from another device** (not mobile IDE): [`0117`](../adr/0117-remote-operator-surface-multidevice.md) *(Proposed)* |
| 28 | - **Agent Notes Core 2.0** (TOML, `knowledge_path`, MCP parity): [`0118`](../adr/0118-agent-notes-core-2-toml-and-knowledge-path.md) *(Accepted)* |
| 29 | |
| 30 | --- |
| 31 | |
| 32 | ## 3. MVVM, feature slices, and “what lives where” |
| 33 | |
| 34 | - **Slices and layers**: [`0006`](../adr/0006-presentation-layers-and-feature-slices.md) |
| 35 | - **Strangler migration and exceptions**: [`0009`](../adr/0009-strangler-migration-and-exceptions.md) |
| 36 | |
| 37 | --- |
| 38 | |
| 39 | ## 4. Transport / backpressure / delivery to UI |
| 40 | |
| 41 | - **Signals, coupling, backpressure**: [`0007`](../adr/0007-signals-coupling-and-ui-backpressure.md) |
| 42 | - **UI thread marshaling**: [`0004`](../adr/0004-ui-thread-marshaling.md) |
| 43 | - **Delivery bus (AFDX analogy)**: [`0094`](../adr/0094-ingestion-bus-afdx-analogy-and-threading-channels.md) |
| 44 | |
| 45 | --- |
| 46 | |
| 47 | ## 5. DAL / CCU / DataBus (pipeline “raw → DTO → UI”) |
| 48 | |
| 49 | - **DAL boundary**: [`0102`](../adr/0102-data-acquisition-layer-boundary-and-contract.md) |
| 50 | - **CCU as fold layer**: [`0097`](../adr/0097-cockpit-compute-units-transport-to-channel-dto.md) |
| 51 | - **CDS (channel → compositor → surface)**: [`0036`](../adr/0036-cds-channel-compositor-surface-pipeline.md) |
| 52 | - **Graph-backed instruments — shared layer inside CDS**: [`0115`](../adr/0115-cds-graph-backed-shared-layer.md) *(Accepted)* |
| 53 | - **IDE DataBus**: [`0099`](../adr/0099-ide-databus-typed-events-and-projections.md) |
| 54 | - **Health stratification**: [`0095`](../adr/0095-workspace-solution-ide-health-stratification.md) *(if you need “what IDE/Solution/Workspace health means”)* |
| 55 | |
| 56 | --- |
| 57 | |
| 58 | ## 6. MCP, agent, and contract testability |
| 59 | |
| 60 | - **MCP contracts + testable infrastructure**: [`0008`](../adr/0008-mcp-contracts-and-testable-infrastructure.md) |
| 61 | - **Agent contract CLI + snapshot tests**: [`0052`](../adr/0052-agent-contract-cli-and-snapshot-tests.md) |
| 62 | - **Visibility of reasoning / provider limits**: [`0020`](../adr/0020-agent-reasoning-visibility-and-provider-limits.md) |
| 63 | - **Intercom (channel, not “chatbot”)**: [`0080`](../adr/0080-intercom-naming-and-multi-party-channel-model.md) |
| 64 | - **Topic cards + spine (topic card index)**: [`0072`](../adr/0072-chat-topic-cards-intent-melody-keyboard-contract.md), [`0096`](../adr/0096-intercom-topic-card-summary-and-product-spine.md) |
| 65 | - **Session tree, steer / follow-up**: [`0116`](../adr/0116-intercom-session-tree-and-agent-message-steering.md) *(Proposed)* |
| 66 | - **Chat persistence (event log)**: [`0045`](../adr/0045-agent-chat-persistence-event-log-and-projections.md) |
| 67 | - **Clarification batches and threads**: [`0031`](../adr/0031-agent-chat-clarification-batches-and-threading.md) |
| 68 | |
| 69 | --- |
| 70 | |
| 71 | ## 7. Code navigation and indexing |
| 72 | |
| 73 | - **Workspace navigation affordances**: [`0039`](../adr/0039-workspace-navigation-affordances.md) |
| 74 | - **Hybrid codebase index core**: [`0105`](../adr/0105-hybrid-codebase-index-for-csharp-web.md) *(Accepted · Implemented)* |
| 75 | - **Hybrid index ↔ CascadeIDE integration**: [`0106`](../adr/0106-hybrid-codebase-index-cascadeide-integration-and-semantic-map.md) |
| 76 | - **HCI and Semantic Map (orientation, three axes)**: [`0113`](../adr/0113-hci-semantic-map-orientation-layer.md) |
| 77 | - **Edge relation type (`relation_kind`)**: [`0114`](../adr/0114-graph-edge-relation-kind-taxonomy.md) |
| 78 | - **Graph kinds (`graph_kind`) and instrument categories**: [`0065`](../adr/0065-instrument-categories-domain-taxonomy.md) |
| 79 | - **Graph-backed surfaces (graph family contract)**: [`0067`](../adr/0067-graph-backed-surfaces-contract.md) |
| 80 | - **Semantic map control flow (PFD)**: [`0053`](../adr/0053-semantic-map-control-flow-pfd.md) *(Accepted · Implemented)* |
| 81 | |
| 82 | --- |
| 83 | |
| 84 | ## 8. Commands and keyboard-first |
| 85 | |
| 86 | - **Command surface & discoverability**: [`0013`](../adr/0013-command-surface-and-discoverability.md) |
| 87 | - **Command palette direct overlay**: [`0070`](../adr/0070-command-palette-direct-overlay-surface.md) |
| 88 | - **Chord stack (Ctrl+K) / FMS-style**: [`0060`](../adr/0060-keyboard-chord-stack-fms-tactical-strategic.md) |
| 89 | |
| 90 | --- |
| 91 | |
| 92 | ## 9. Where to keep “current architecture” description |
| 93 | |
| 94 | ADR records decisions and motivation. For “how it works now” use: |
| 95 | - `docs/en/architecture/current-architecture-v1.md` (canonical entry — this tree) |
| 96 | - `docs/en/ui-ux/cascade-ide-ui-layout-v1.md` (layout / region names reference) |
| 97 | - `docs/MCP-PROTOCOL.md` (MCP contract reference) |
| 98 | |
| 99 | Version: **v1**. |
| 100 | |