Skip to content

Commit 65f0bfd

Browse files
tdorauintctdorauintc
committed
After step 4
1 parent 76be159 commit 65f0bfd

1 file changed

Lines changed: 132 additions & 0 deletions

File tree

‎docs/agent/intermediate/adr-vs-design-split.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Content Split — ADR vs. Design Doc
2+
3+
> **Purpose:** Decide which content from [diagrams-summary.md](./diagrams-summary.md) and [responsibilities.md](./responsibilities.md) belongs in the ADR (`docs/adr/0012-mlops-integration-reuse.md`) versus a follow-up Design Doc. Follows the guidance in [../../../docs/README.md](../../README.md):
4+
>
5+
> - **ADR** = *What did we decide and why?* — short, decision-focused (1–2 pages).
6+
> - **Design Doc** = *How will we implement this?* — detailed blueprint (5–20 pages).
7+
>
8+
> This intermediate is a working artifact: it does not need to follow either template and will be used to seed the design doc later.
9+
10+
---
11+
12+
## ADR scope (goes into `0012-mlops-integration-reuse.md`)
13+
14+
The ADR captures the **architectural decisions** SceneScape commits to. It is intentionally short and avoids implementation detail.
15+
16+
### Context (ADR)
17+
18+
- SceneScape today owns custom solutions for model download/management and visual pipeline building (static JSON configs + custom generator → K8s config maps with pod recreation).
19+
- The Open-Edge-Platform now offers (or will offer) reusable components covering these capabilities: Model Downloader, ViPPET, DLSPS (existing, evolving), and the new Stream Manager.
20+
- Maintaining SceneScape-specific implementations of these capabilities is redundant, costly, and divergent from the platform direction.
21+
- Motivation is broader than UX: engineering efficiency, focus on core SceneScape functionalities (spatial awareness, sensor fusion, tracking), reduction of redundant effort across OEP.
22+
23+
### Decision (ADR)
24+
25+
- **Delegate** model management, visual pipeline building, and video-source acquisition to platform components; **reuse** them in place of SceneScape-specific implementations.
26+
- Component assignments (one-sentence form, full detail in responsibilities matrix lives in the design doc):
27+
- **Model Downloader** — model lifecycle.
28+
- **ViPPET** — pipeline authoring; SceneScape consumes pipeline definitions via **REST pull**.
29+
- **DLSPS** — pipeline execution; evolve from static JSON / pod recreation toward runtime pipeline API, staged.
30+
- **Stream Manager** — camera discovery, video capture, livestream/replay; **optional** dependency for SceneScape.
31+
- **Geti** — model training; **no direct SceneScape↔Geti integration** (mediated via Model Downloader and Stream Manager).
32+
- **SceneScape retains ownership** of: scene model, scene-level pipeline-to-source mapping, pipeline runtime orchestration against DLSPS, multimodal fusion/tracking, scene export/import.
33+
- **Exported scenes embed pipeline definitions by value** so deployment is possible without ViPPET.
34+
- **Backwards compatibility:** existing static JSON pipeline configs (Docker bind-mount and K8s config maps) remain supported until feature parity with the ViPPET-based flow is achieved.
35+
- **Phased rollout** (Phase names only; no release numbers):
36+
- *Foundation* — ADR + design baseline.
37+
- *Model Management Delegation* — adopt shared model volume populated by Model Downloader.
38+
- *Pipeline Building Delegation & Stream Manager Adoption* — Stream Manager consumption, scene-level pipeline-to-source mapping, scene export/import.
39+
- *Pipeline Building Delegation & Stream Manager Adoption – Part 2* — full ViPPET pipeline-definition consumption, evolved DLSPS runtime integration.
40+
41+
### Alternatives Considered (ADR)
42+
43+
- **Status quo: keep custom SceneScape implementations** (model installer, pipeline generator, direct camera sources). Pros: no integration work. Cons: redundant with platform, ongoing maintenance, divergence from OEP roadmap, blocks DLSPS evolution.
44+
- **Push pipeline-to-source mapping into ViPPET.** Pros: single source of pipeline metadata. Cons: scene-level binding is a SceneScape domain concept (cameras serve scene-specific spatial-awareness tasks); ViPPET would need scene awareness it does not own.
45+
- **Direct SceneScape↔Geti integration for models.** Pros: fewer hops. Cons: duplicates Model Downloader, couples SceneScape to a training-platform API, breaks the platform's intended separation of concerns.
46+
- **Push pipeline definitions by reference (ID/version) in exported scenes.** Pros: smaller artifact. Cons: deployment requires ViPPET to be reachable; violates the "deployable without ViPPET" requirement.
47+
- **Make Stream Manager a hard dependency.** Pros: uniform video acquisition. Cons: regresses today's direct-source deployments; out of step with optional adoption goal.
48+
- **Skip the staged DLSPS transition; require runtime pipeline API up front.** Pros: simpler end-state. Cons: blocks delivery; today's pod-recreation flow already works and must keep working until DLSPS evolves.
49+
50+
### Consequences (ADR)
51+
52+
**Positive**
53+
54+
- Smaller SceneScape surface area: removes custom model installer and pipeline generator over time.
55+
- Clear separation of concerns aligned with OEP architecture.
56+
- SceneScape team focus shifts to core spatial-awareness value.
57+
- Deployments remain operable without ViPPET (self-contained exported scenes) and without Stream Manager (optional dependency).
58+
- Staged transition preserves existing deployments.
59+
60+
**Negative**
61+
62+
- Cross-component dependency on Model Downloader, ViPPET, DLSPS evolution, and Stream Manager delivery timelines.
63+
- Temporary duality: both legacy static JSON flow and new ViPPET-based flow coexist until parity.
64+
- New runtime call from SceneScape to Model Downloader's listing endpoint adds a small new integration surface.
65+
- Co-ownership of model storage between ViPPET and Model Downloader (when co-deployed) requires the deployment design to disambiguate.
66+
67+
### References (ADR)
68+
69+
- Component Interaction diagram: [SceneScape_MLOps-Component Interaction.drawio.svg](../diagrams/SceneScape_MLOps-Component%20Interaction.drawio.svg)
70+
- Follow-up Design Doc (to be written separately): `docs/design/mlops-integration-reuse.md` (placeholder)
71+
72+
---
73+
74+
## Design-Doc scope (goes into the follow-up design doc)
75+
76+
The Design Doc explains **how** SceneScape implements the decisions above. It is the right home for everything below.
77+
78+
### Architecture & interaction detail
79+
80+
- Full responsibility matrix per component (Section 1 of [responsibilities.md](./responsibilities.md)).
81+
- Cross-cutting concerns table (Section 2 of `responsibilities.md`).
82+
- Process Model walkthrough (stages 1–7) and Component Interaction edges (Section 1 and 2 of [diagrams-summary.md](./diagrams-summary.md)).
83+
- Per-contract specification:
84+
- SceneScape↔Stream Manager (livestream/replay APIs consumed; optional dependency mode).
85+
- SceneScape↔ViPPET (REST pull for pipeline definitions; pull cadence; auth; versioning).
86+
- SceneScape↔DLSPS (today: pod recreation in K8s; target: runtime pipeline API; MQTT inference output topic conventions).
87+
- SceneScape↔Model Downloader (deployment-time job semantics; runtime listing endpoint usage; shared-volume conventions).
88+
- SceneScape↔Geti (none; document why and what indirection looks like).
89+
90+
### SceneScape-side deltas — implementation
91+
92+
For each of the 6 deltas (Section 3 of `responsibilities.md`):
93+
94+
- Affected modules (`model_installer`, `manager/src/manager/ppl_generator`, `manager/src/manager/kubeclient.py`, controller pipeline orchestration, scene export/import, DLSPS adapter `dlstreamer-pipeline-server/user_scripts/gvapython/sscape`).
95+
- Migration plan and parity criteria for retiring the legacy static-JSON / pipeline-generator flow.
96+
- Compatibility shims and feature flags (if any).
97+
- Test strategy per delta (unit/functional/integration/UI).
98+
99+
### Scene export/import format
100+
101+
- Schema of the exported scene artifact (pipelines embedded by value).
102+
- Parametrization mechanism for embedded pipeline definitions (deferred from ADR resolutions; to be specified here).
103+
- Model identification scheme on the shared volume (paths, naming, versions).
104+
105+
### Phased rollout — execution plan
106+
107+
- Per-phase concrete tasks, exit criteria, and rollback points.
108+
- Mapping of phases to the 6 deltas (already pre-decided in `responsibilities.md` §4.3; design doc adds task-level breakdown).
109+
- Backwards-compatibility window: when each legacy mechanism may be removed.
110+
111+
### Deployment topology
112+
113+
- Docker Compose and Kubernetes wiring for the shared model volume.
114+
- Model Downloader as standalone vs. embedded in ViPPET deployment (co-ownership of model storage).
115+
- Stream Manager opt-in deployment.
116+
- DLSPS configuration for both interim (config-map + pod recreation) and target (runtime API) modes.
117+
118+
### Risks & open items deferred from ADR
119+
120+
- Pipeline definition parametrization details.
121+
- Exact criteria for "feature parity" gate before retiring legacy JSON/pipeline-generator flow.
122+
- gvapython → Gst Analytics Python migration plan for the SceneScape adapter (called out in the JIRA roadmap; design-level activity).
123+
124+
---
125+
126+
## Out of scope for both documents
127+
128+
- Geti-side integration timeline with ViPPET / Model Downloader / Stream Manager.
129+
- Stream Manager's own API design (owned by the Stream Manager team).
130+
- ViPPET's internal pipeline templates and verification tooling.
131+
- Concrete UX flows in the SceneScape Manager UI (separate UX/feature work).
132+
- Release dates, JIRA IDs, GitHub issue numbers.

0 commit comments

Comments
 (0)