Skip to content

Legacy Integration and Salvage Notes

These notes are derived from a research pass over the previous Substrate platform codebase (2026-03-29) to determine what patterns and components can be salvaged.

Reusable Patterns

1. OpenAPI Contract Enforcement

The most valuable pattern to carry forward is contract enforcement between the frontend and the OpenAPI spec. - Contract Verification: Use CI scripts to scan frontend API callers and verify they only use endpoints defined in the generated OpenAPI spec. - Drift Checks: Implement CI guardrails to ensure substrate-api/openapi.* and ui/src/types/api.generated.ts are always in sync.

2. WebSocket/SSE Streaming Client

The previous platform's ws.client.ts provide a robust structure for real-time notifications: - Reconnect Logic: Exponential backoff for reconnection. - Heartbeat: Health monitoring for persistent connections. - Subscription Registry: Managing subscriptions by channel (e.g., notifications, module-health).

3. OPA Engine Hardening

Practical OPA runtime ideas to implement in policy_runtime: - Reloadable Bundles: Parse and compile policies from disk on reload. - Prepared-Eval Cache: Keep a compiled policy engine in memory for performance. - Exception Sync: Synchronize approved exceptions into OPA data at runtime. - Path Sanitization: Ensure policy paths are safe before writing files.

Partially Salvageable Components

  • Domain-Specific Query Keys: Segment frontend cache invalidation by domain (e.g., LLM endpoints, marketplace config, org settings).
  • Service Extraction Plan Format: Use a consistent format for service extraction documents (scope, dependencies, NATS topics, contract-test checklist).

Components to Avoid (Do Not Salvage)

  • Old Auth Stack: Do not revive Authentik-based assumptions or the previous split-auth model. Keycloak is the current authority.
  • Monolithic Gateway Implementation: Avoid the "god module" pattern found in previous backend implementations.
  • Unpinned Code Generation: All generator tools and CLI versions must be pinned to avoid drift.
  • Theme Drift: Do not introduce a second theme system; the "Obsidian Atlas" system in ui/theme.md is the only visual source of truth.