Skip to content

Review Playbook

This playbook standardizes security/correctness reviews for the IDTA Submodel Editor.

Scope

  • Core stack is always required: backend API, frontend app, export flow, and core docker compose startup.
  • Optional modules are reviewed when touched or explicitly requested:
  • Magic Import profile
  • Dataspace profile
  • PLC profile

Severity Model

  • P0: exploitable security/data loss/system unusable.
  • P1: core workflow broken or materially unreliable.
  • P2: correctness edge cases/performance/maintainability blockers.
  • P3: docs/polish/cleanup.

Mandatory Rule

No fix ships without a test.

Deployment Governance Prerequisite

Repository admins must enforce branch protection/rulesets on main (or an explicitly designated default branch) and any release branches, with required status checks and required pull requests. This playbook assumes those controls are active.

Baseline Verification

Run before review coding begins. Execute commands from repo root.

# Integration/E2E context only
docker compose up -d
# ...run integration/e2e checks...
docker compose down

# Backend-only changes
PYTHONPATH=backend pytest backend/tests

# Frontend changes
npm --prefix frontend run lint
npm --prefix frontend run type-check
npm --prefix frontend run test:unit

# Docs/process changes
mkdocs build --strict

Required Review Checks

  1. Backend API consistency
  2. Standardized error envelopes and status mapping.
  3. Correlation ID propagation.

  4. Deterministic route registration and OpenAPI behavior.

  5. Feature flag behavior

  6. Disabled features must not execute runtime calls.

  7. /api/settings and /api/settings/features must agree on effective runtime flags.

  8. Template pipeline

  9. Fetcher cache + upstream error handling.

  10. Validation correctness for cardinality/type/reference constraints.

  11. Tool registry

  12. Dependency ordering.
  13. Stable /api/tools/manifest ordering.

  14. Accurate enabled/initialized reporting.

  15. Frontend tool integration

  16. Wizard steps derived from manifest metadata.

  17. Fallback behavior when backend manifest unavailable.

  18. Security checks

  19. Upload validation constraints.
  20. Secret handling and production guardrails.
  21. External call timeouts/error handling.

Test Matrix

  • Scoped baseline:
  • Backend changed: PYTHONPATH=backend pytest backend/tests
  • Frontend changed: npm --prefix frontend run lint
  • Frontend changed: npm --prefix frontend run type-check
  • Frontend changed: npm --prefix frontend run test:unit
  • Docs or .github process files changed: mkdocs build --strict
  • Runtime integration or contracts changed: run docker compose + E2E smoke
  • Optional, only when affected:
  • E2E_PROFILE=magic-import npm --prefix frontend run test:e2e
  • E2E_PROFILE=dataspace npm --prefix frontend run test:e2e
  • E2E_PROFILE=plc npm --prefix frontend run test:e2e

Delivery Requirements

Each review cycle must produce:

  1. REVIEW_REPORT.md with prioritized findings.
  2. Small, theme-focused PRs.
  3. Tests for each fix/enhancement.
  4. Updated docs for behavior or contract changes.