Skip to content

SYS-003 - Develop/Main Integration Context Model (Master Spec)

Summary

Define a reliable cross-repo workflow where backend and frontend teams can integrate rapidly on develop, while main remains release/stable. This model adds dual-channel context and contract flows:

  • develop = preview/integration channel
  • main = stable/release channel

The goal is to eliminate integration ambiguity between repos during active development while preserving strict production safety.

Problem Statement

Current team behavior integrates APIs and UI primarily on develop, but existing context/sync assumptions are mostly main-centric. This causes:

  • uncertainty about where latest integration truth lives
  • delayed UI integration for backend changes
  • potential drift between repo-local assumptions and platform context
  • inconsistent AI assistant behavior across repositories

User Scenarios (mandatory)

User Story 1 - Backend publishes preview contracts on develop (Priority: P1)

As a backend developer, when I merge API changes to develop, a preview contract/types artifact is published so UI teams can integrate immediately.

Independent Test: API endpoint changes merged into reservation-api-server:develop produce a preview contract package and trigger consumer preview validation workflows.

User Story 2 - UI integrates on preview channel without waiting for main (Priority: P1)

As a UI developer, I can consume preview API types from develop and validate integration before backend release to main.

Independent Test: A UI PR on develop can typecheck and test against preview types without any manual contract copying.

User Story 3 - Release stability remains tied to main channel (Priority: P1)

As a release owner, I can trust that main contracts are stable and protected, and production validation uses stable channel only.

Independent Test: Stable contract publication only happens on main, and branch protections prevent bypassing release checks.

User Story 4 - Platform context reflects both channels clearly (Priority: P2)

As a platform maintainer, I can distinguish preview vs stable updates in bz-platform-context and avoid misinterpreting in-flight changes as release truth.

Independent Test: Sync metadata entries carry explicit channel tags (preview vs stable) and branch/ref metadata.

Functional Requirements (mandatory)

  • FR-001: Repositories MUST support dual-channel context signaling:
  • develop signals tagged preview
  • main signals tagged stable
  • FR-002: Backend contract publishing MUST produce:
  • preview artifacts from develop
  • stable artifacts from main
  • FR-003: Frontend repos MUST validate against preview channel on develop and stable channel on release/main paths.
  • FR-004: main branch protections MUST remain stricter than develop protections in all in-scope repos.
  • FR-005: bz-platform-context sync-state records MUST include source branch context so automation and humans can distinguish preview/stable.
  • FR-006: AI contributor guidance (AGENTS.md and rules) MUST explicitly document branch/channel semantics.
  • FR-007: Contract drift checks MUST block release promotion if preview work has unresolved incompatibilities against stable expectations.

Non-Goals

  • Full repository mirroring into bz-platform-context
  • Replacing human architecture decisions with automation
  • Forcing every repo to adopt develop if that repo is release-only

Proposed Workflow

Channel model

Branch Channel Purpose Consumers
develop preview integration velocity backend + frontend developers
main stable release and production correctness release managers, ops, prod CI

Context sync model

  • Sync callers trigger on high-signal changes for both branches.
  • Metadata includes channel tags:
  • preview on develop
  • stable on main
  • bz-platform-context remains metadata/control-plane, not code mirror.

Contract model

  • Backend:
  • publish preview contracts/types from develop
  • publish stable contracts/types from main
  • Frontends:
  • consume preview contracts on develop
  • validate stable contracts pre-release

AI Workflow Strategy (agents, MCP, skills)

Use existing first

  • Reusable workflows in bz-platform-context
  • Existing MCP servers:
  • GitHub operations
  • docs/context retrieval
  • browser validation where needed
  • Existing spec lifecycle automation

Build custom selectively

Custom skills should be created before custom MCP servers.

Initial high-value skills:

  1. bookingzone-api-change
  2. frappe-doctype-safe-update
  3. cdk-safe-infra-change
  4. cross-repo-impact-check
  5. integration-debug-preview-vs-stable

Custom MCP investment should only begin after two sprints of evidence that skills + existing tooling are insufficient.

Success Criteria

  • SC-001: 90% of backend API changes merged to develop become consumable by UI repos within 30 minutes via preview contracts.
  • SC-002: 0 high-severity integration defects caused by preview/stable confusion after rollout.
  • SC-003: 0 direct pushes to protected main across in-scope repos.
  • SC-004: First-pass AI task completion rate improves by 25% after skill rollout on pilot repositories.
  • SC-005: Mean time to diagnose cross-repo integration mismatch drops below 15 minutes using sync metadata + contract checks.

Repo Impact Summary

  • reservation-api-server
  • dual contract publish lanes (preview/stable)
  • sync tags by branch
  • admin-web-app / venuplus-app
  • dual-lane contract consumption and checks
  • sync tags by branch
  • customer-web-app (deferred for now)
  • excluded from active sync rollout in current phase
  • may rejoin via follow-up spec amendment
  • bz-platform-context
  • governance docs and runbooks for channel semantics
  • sync-state interpretation guidance

Rollout Order

  1. Document and approve channel policy (this spec).
  2. Merge sync-caller PRs into develop first for frontend repos, then promote to main after integration validation.
  3. Implement backend preview contract publish from develop.
  4. Implement frontend preview consumption/validation flows.
  5. Add release gate checks for preview/stable drift.
  6. Roll out initial project skills and measure outcomes.
  7. Apply/verify branch protection baselines.

Risks and Mitigations

  • Risk: Preview channel noise overwhelms context consumers.
  • Mitigation: high-signal path filters + explicit preview tag.
  • Risk: Teams accidentally treat preview as release truth.
  • Mitigation: stable-only release gates and docs.
  • Risk: Added automation complexity slows delivery.
  • Mitigation: phased rollout with measurable checkpoints.

Decisions Confirmed

  1. Support both develop and main channels.
  2. Preview contract versioning is approved.
  3. Release gate for preview/stable drift is approved.
  4. Branch protection split (main stricter than develop) is approved.
  5. Operational sequence: merge the 3 frontend sync-caller PRs into develop first, then promote to main after validation.