# Feature Specification: Edge Proxy Uncontainerized > For the complete documentation index, see [llms.txt](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/llms.txt). **Feature Branch**: `002-edge-proxy-uncontainerized` **Created**: 2026-03-29 **Status**: Implemented (pending release tag) **Input**: Transition delta from `001-baseline-uncontainerized-parity` ## User Stories * As a developer, I want browser traffic to flow through one edge endpoint so local setup is simpler. * As a developer, I want backend services to keep existing contracts while edge routing is introduced. * As a maintainer, I want this state to remain generated from specs with full parity checks. * As a learner, I want state-aware header/About UX carried from state `001` and visible through the edge endpoint. * As a learner, I want a `Status` page that shows service uptime/health through the edge runtime. ## Functional Requirements * FR-201: The state SHALL expose a single browser-facing edge endpoint for baseline UI traffic. * FR-202: The edge SHALL route requests to existing backend services without changing current API contracts. * FR-203: Existing baseline end-to-end flows F1-F6 SHALL remain behaviorally compatible. * FR-204: The edge endpoint SHALL expose a standalone API explorer at `/api/docs`, backed by state API metadata and service OpenAPI specs. * FR-205: GUI state-awareness requirements from state `001` (header title with state id + About page metadata/linkage/API explorer link) SHALL be preserved in this state. * FR-206: GUI top navigation SHALL include a `Status` tab/link in this state and later states in this lineage unless explicitly superseded. * FR-207: The `Status` page SHALL render uptime/health status for each runtime service participating in this state. * FR-208: Status-page service status data SHALL be obtained through edge-accessible health/status sources so the page works from the single edge endpoint. * FR-209: From state `002` onward, the header top-right area SHALL include a `System` dropdown menu. * FR-210: The `System` menu SHALL include an `API Explorer` entry bound to `StateUiMetadata.apiExplorerUrl` when `StateUiMetadata.features.apiExplorer` is `true`. * FR-211: The `System` menu SHALL include an `About` entry routing to `/about`. * FR-212: The `System` menu SHALL include a `Status` entry routing to `/status` when `StateUiMetadata.features.statusPage` is `true`, and SHALL hide the entry when that flag is `false`. * FR-213: The header title SHALL always render the active state id from `StateUiMetadata.stateId` (not a hard-coded title string). * FR-214: State-specific header overrides in `generation/frontend-overrides/web-front-end/angular/main/app/header/` SHALL preserve the `System` menu items and state-id title behavior unless a later approved spec explicitly supersedes one or more of these requirements. * FR-215: The `System` menu SHALL include an `API Explorer` entry only when `StateUiMetadata.features.apiExplorer` is `true`. * FR-216: The `System` menu SHALL include a `Pub/Sub Inspector` entry only when `StateUiMetadata.features.pubSubInspector` is `true`; when present it SHALL navigate via `StateUiMetadata.pubSubInspectorUrl`. ## Non-Functional Requirements * NFR-201: Browser calls SHALL no longer require direct cross-origin access to every backend service port. * NFR-202: Runtime SHALL remain uncontainerized in this state. * NFR-203: State generation SHALL remain deterministic from spec inputs. * NFR-204: State SHALL pass conformance, smoke, and docs validation before release tagging. * NFR-205: Generated state branches from `002+` SHALL include dependency security scanning and Node.js license scanning workflows appropriate to the components present in the generated codebase. * NFR-206: CVE suppression files used by scanning workflows (`.github/*-cve-ignore-list.xml`) SHALL be present in generated branches and updated when state dependency sets change. * NFR-207: CI workflow component coverage SHALL be derived from generated state component inventory, and SHALL remain complete for all applicable language/runtime components. * NFR-208: States `003+` SHALL inherit this generated-branch CI baseline unless a later state explicitly replaces it. * NFR-209: Every generated Node.js project (`package.json`) SHALL declare `"license": "Apache-2.0"`; new Node services introduced in later states MUST inherit this default unless an explicit state requirement overrides it. * NFR-210: The edge proxy implementation SHALL forward standard ingress headers (`X-Forwarded-For`, `X-Forwarded-Host`, `X-Forwarded-Proto`, and `X-Forwarded-Prefix` for prefixed routes) to upstream services. * NFR-211: Generated-state publish flows SHALL require successful compile preflight for all generated modules declared in state metadata (Node.js, Gradle, .NET where present) before commit/push. * NFR-212: API explorer "Try it out" requests in edge-proxy states SHALL honor service path prefixes (for example `/order-matcher`, `/people-service`) and MUST NOT fallback to root-relative service paths. * NFR-213: Runtime/start scripts for this state SHALL detect and report currently generated state id versus expected state id before startup. * NFR-214: On state mismatch, runtime/start scripts SHALL provide explicit guidance for forward-regeneration versus backward clean rebuild decisions. * NFR-215: Runtime/start scripts SHALL support an explicit opt-in mode to auto-regenerate expected state before startup. * NFR-216: Generated-state snapshot pruning and generated CI module discovery SHALL be state-scoped; components not in the active state's runtime inventory (for example legacy Node edge-proxy in `004+` states) MUST be excluded unless explicitly reintroduced by a later approved state spec. * NFR-217: From state `002` onward, `HeaderComponent` SHALL inject `StateMetadataService` and consume `metadata$` for state-id title and `System` menu metadata wiring. * NFR-218: The `System` menu + state-aware title pattern SHALL be treated as a cross-cutting UI contract; state-specific additions (for example new tabs or status pills) MUST compose with that contract and MUST NOT replace it. * NFR-219: Smoke suites for states `002` through `014` SHALL assert presence of the `System` menu toggle, `About` link, conditional `Status` link, conditional `API Explorer` link, conditional `Pub/Sub Inspector` link, and state-id title rendering contract via shared web UX contract checks. * NFR-220: Generated `assets/state-ui.json` status checks SHALL be state-lineage aware: they MUST include all active runtime services introduced by earlier states (for example `price-publisher` from `008+`, `order-matcher` from `009+`) and MUST remove superseded checks when a runtime substrate is replaced (for example `trade-feed` after `006` NATS migration). * NFR-221: Generation SHALL fail when UI status metadata is inconsistent with lineage invariants (missing required service checks, stale superseded checks, duplicate ids, or malformed check definitions). * NFR-222: Before generated-state branch commit/push, publish automation SHALL enforce a prepublish CI-parity gate that validates contracts, dependency/version targets, lineage/UI invariants, module compile preflight, Node license policy, container image buildability, and dependency CVE scanning; gate failures MUST block branch generation/publish unless an explicit operator override is provided. * NFR-223: Browser-offered documentation/tool URLs (`/api/docs/`, API explorer navigation links, and conditional `pubSubInspectorUrl` links when enabled in later lineage states) SHALL return non-404 responses with browser-renderable content types (HTML for pages, JSON for catalog payloads). ## Success Criteria * SC-201: UI works end-to-end through the edge endpoint for baseline flows. * SC-202: No contract drift relative to approved contracts unless explicitly updated in this pack. * SC-203: Generated snapshot is tagged and linked to validation evidence. * SC-204: Generated snapshots from this state lineage contain required CI workflow files and scanner suppression files with component-complete coverage. * SC-205: Generated-state publish fails prior to commit/push when compile preflight fails for any generated module in scope. * SC-206: After state startup, API explorer is reachable at `http://localhost:18080/api/docs`, interactive requests route through prefixed service paths, and browser-offered docs/tool URLs satisfy non-404 + expected content-type contracts. * SC-207: Edge-routed UI smoke tests verify header title includes `002-edge-proxy-uncontainerized`, `About` page metadata renders expected lineage/source fields, and conditional system-menu tooling links (API explorer + pub/sub inspector where enabled) are available. * SC-208: Edge-routed UI smoke tests verify `Status` page is reachable and shows per-service uptime/health entries for this state. * SC-209: Startup script smoke checks verify generated-state detection messaging for both match and mismatch cases, including opt-in auto-regeneration flow. * SC-210: Publishing snapshots and generated CI metadata for states `004+` excludes the Node `edge-proxy` module unless a later state spec explicitly restores it. * SC-211: Header override regressions that drop `StateMetadataService` wiring, state-id title rendering, or required `System` menu items fail state smoke checks before publish. * SC-212: Generation-time validation fails for any state whose generated status metadata omits required runtime checks (including `price-publisher`/`order-matcher` where applicable) or retains deprecated checks (for example `trade-feed` after state `006`). * SC-213: Generated-state publish fails before commit/push when `pipeline/prepublish-generated-state-gate.sh` reports any prepublish CI-parity gate failure. ## Generation + Runtime Entry Points * generation: `bash pipeline/generate-state.sh 002-edge-proxy-uncontainerized` * runtime (first run/build): `./scripts/start-state-002-edge-proxy-generated.sh --build-only` * runtime (start after build): `./scripts/start-state-002-edge-proxy-generated.sh` * smoke test: `./scripts/test-state-002-edge-proxy.sh`