Epic: MVP - Vendor-neutral Flow Insight Overlay with GitHub, GitLab, and a controllable GitLab CE test harness

[ourchitectureio]

Summary

Build an API-first MVP that interprets development flow signals across source control and CI systems through one shared semantic model, starting with:

• GitHub SaaS adapter
• GitLab SaaS adapter
• GitLab self-managed adapter
• GitLab CE or self-managed container harness for deterministic end-to-end testing

This MVP must prove one shared capability contract with multiple implementations and multiple provider inputs. It must not become a GitHub-only abstraction, a workflow replacement, a generic CMDB, or a stack-specific product line.

Why

The IDP should prove that it is:

• not a GitHub-only abstraction
• not a workflow replacement
• not a generic CMDB
• not a stack-specific implementation exercise

It should prove that it can:

• normalize real provider signals through a provider-neutral contract
• infer actionable flow insights through an explainable read-only core
• expose those insights consistently through HTTP API and MCP
• support embedded clients like Backstage without letting UI shape the domain
• preserve one capability model across multiple implementation stacks

Strategic guardrails

This epic is capability-first, not implementation-first.

The center of gravity for this work is:

• the canonical flow and signal model
• the normalized provider adapter contract
• the inferred insight shape
• the scenario fixtures and contract protections

The center of gravity for this work is not:

• one provider API
• one reference stack
• one storage schema
• one event pipeline
• one UI surface

Preserve these principles throughout execution:

• one shared capability contract, multiple implementations
• thin provider adapters
• explainable read-only inference
• stable transport contracts
• controlled harnesses validate behavior but do not define truth
• model what changes action, reference the rest

In scope

• vendor-neutral canonical signal model
• provider adapter contract
• ADR for MVP technical foundations
• GitHub SaaS adapter
• GitLab adapter with SaaS and self-managed support
• GitLab CE or self-managed container harness
• read-only signal inference
• HTTP API
• MCP read tools
• initial Backstage surface
• scenario-based contract and integration tests
• MVP boundaries and provider strategy documentation

Out of scope

• write-back automation
• full workflow engine behavior
• broad entity modeling
• heavy governance engine
• standalone flow service decomposition for this slice
• storage platform expansion beyond what is needed for the MVP
• event-sourced architecture as a prerequisite for the MVP
• VS Code client in this first slice

Hard constraints

• No implementation-heavy work should outrun the semantic model and provider contract
• No provider adapter should leak provider-specific concepts into the core unnecessarily
• No transport surface should define the core model
• Backstage must consume the IDP API rather than provider APIs directly
• MCP must expose the same core meaning as HTTP, not a separate model
• The controlled GitLab harness must validate boundaries and behavior, not become the semantic source of truth
• The MVP must remain read-only and explainable
• The project must preserve the broader IDP direction of one shared capability contract that can be satisfied by multiple stacks

Execution sequence

Phase 0: shared foundations first

1. Define the canonical MVP flow and signal model #220 Define the canonical MVP flow and signal model
2. Define the provider adapter contract for source control and CI flow inputs #221 Define the provider adapter contract for source control and CI flow inputs
3. ADR: Lock MVP flow observation technical foundations #231 Decisions for flow observations MVP
4. Document MVP boundaries and provider strategy #230 Document MVP boundaries and provider strategy
5. Add scenario-based contract and integration tests for provider-neutral flow insights #229 Early scenario and fixture scaffolding

No implementation-heavy work in #222, #223, #224, #225, #226, #227, or #228 should redefine or outrun these decisions.

Phase 1: provider and core implementation

After the semantic model, provider contract, and technical foundations are stable enough:

6. Implement GitHub SaaS adapter for MVP flow inputs #222 Implement GitHub SaaS adapter for MVP flow inputs
7. Implement GitLab adapter with support for SaaS and self-managed instances #223 Implement GitLab adapter with support for SaaS and self-managed instances
8. Add GitLab CE/self-managed container harness for deterministic end-to-end testing #224 Add GitLab CE or self-managed container harness for deterministic end-to-end testing
9. Implement the read-only signal inference engine #225 Implement the read-only signal inference engine

Phase 2: shared transports

After the inference contract stabilizes:

10. Expose flow insights through the HTTP API #226 Expose flow insights through the HTTP API
11. Expose flow insights through MCP read tools #227 Expose flow insights through MCP read tools

These transport surfaces must expose the same shared insight contract. They do not define it.

Phase 3: embedded client

Only after the API surface is stable:

12. Create an initial Backstage view for flow insights #228 Create an initial Backstage view for flow insights

Backstage must consume the API and must not drive the domain model.

Phase 4: consolidation

Then complete and tighten the final protections:

13. Add scenario-based contract and integration tests for provider-neutral flow insights #229 Add scenario-based contract and integration tests for provider-neutral flow insights
14. Document MVP boundaries and provider strategy #230 Complete MVP boundaries and provider strategy documentation

Child issues

• Define the canonical MVP flow and signal model #220 Define the canonical MVP flow and signal model
• Define the provider adapter contract for source control and CI flow inputs #221 Define the provider adapter contract for source control and CI flow inputs
• ADR: Lock MVP flow observation technical foundations #231 ADR: Lock MVP flow insight technical foundations
• Implement GitHub SaaS adapter for MVP flow inputs #222 Implement GitHub SaaS adapter for MVP flow inputs
• Implement GitLab adapter with support for SaaS and self-managed instances #223 Implement GitLab adapter with support for SaaS and self-managed instances
• Add GitLab CE/self-managed container harness for deterministic end-to-end testing #224 Add GitLab CE or self-managed container harness for deterministic end-to-end testing
• Implement the read-only signal inference engine #225 Implement the read-only signal inference engine
• Expose flow insights through the HTTP API #226 Expose flow insights through the HTTP API
• Expose flow insights through MCP read tools #227 Expose flow insights through MCP read tools
• Create an initial Backstage view for flow insights #228 Create an initial Backstage view for flow insights
• Add scenario-based contract and integration tests for provider-neutral flow insights #229 Add scenario-based contract and integration tests for provider-neutral flow insights
• Document MVP boundaries and provider strategy #230 Document MVP boundaries and provider strategy

Success criteria

• The core signal model works across both GitHub and GitLab
• The provider adapter contract is clear enough that adapters stay thin and the core remains provider-neutral
• The technical foundations ADR locks the MVP approach for inference, storage boundaries, eventing approach, fixture strategy, equivalence expectations, transport ownership, and deferred scope
• At least six high-value flow insights are inferred from real or controlled provider data
• The same insight shape is exposed through HTTP API and MCP
• A simple Backstage view renders prioritized insights without raw event dumping
• GitLab CE or self-managed can be used as a repeatable local and CI harness
• Scenario-based tests protect provider-neutral semantics and cross-stack equivalence where expected
• The MVP remains read-only, explainable, and clearly bounded

Verification signals

This epic is progressing correctly if:

• shared semantic and contract docs land before implementation-heavy work expands
• scenario fixtures and contract protections arrive early enough to shape implementation
• provider adapters normalize into one contract rather than inventing parallel models
• the inference engine operates on normalized inputs rather than raw provider shapes
• HTTP API and MCP expose the same core meaning
• Backstage remains a consumer of the capability rather than the owner of it
• multiple implementations can satisfy the same capability without shared internals

Notes

This epic should prove provider-neutral interpretation and multi-implementation portability, not just provider integration coverage.

Useful phrases to preserve:

• one shared capability contract, multiple implementations
• three adapters, one core model, one controlled harness
• model what changes action