Skip to main content

Implementation Plan: Simple App - Base Uncontainerized App

Branch: 001-baseline-uncontainerized-parity | Date: 2026-03-28 | Spec: /specs/001-baseline-uncontainerized-parity/spec.md
Input: Feature specification from /specs/001-baseline-uncontainerized-parity/spec.md

Summary​

Capture and enforce TraderX baseline runtime behavior in canonical Spec Kit feature artifacts at repo root, while preserving current generated runtime behavior and compatibility contracts.

Generation Approach​

Spec Kit is the requirements/planning workflow and does not impose a single code-emission engine.
For TraderX baseline parity, generation uses this chain:

  1. Plain-English FR/user-story requirements define behavior.
  2. Technical NFRs define implementation shape (language/framework/ports/env/contracts/dependencies).
  3. Component manifests compile deterministic generation inputs.
  4. Synthesis generators emit code from manifests and templates.
  5. Conformance + semantic compare gates verify closeness to approved baseline.

Technical Context​

Language/Version: Java 21 (Spring Boot services), TypeScript/Node.js (Nest + Socket.IO + Angular), C# (.NET 9), SQL (H2)
Primary Dependencies: Spring Boot, Gradle, NestJS, Socket.IO, ASP.NET Core, Angular, H2
Storage: H2 over TCP/PG/Web ports
Testing: Existing overlay smoke scripts in scripts/*.sh
Target Platform: Local developer workstation (macOS/Linux), pre-containerized process runtime
Project Type: Distributed multi-service web application
Performance Goals: Functional parity and deterministic startup/health behavior over raw throughput
Constraints: Contract compatibility, CORS in pre-ingress mode, stable port mapping, no hidden hydration dependency
Scale/Scope: 9 baseline processes/services + Angular UI

Constitution Check​

  • Pass: Root-level feature-scoped spec pack created.
  • Pass: Contract compatibility explicitly gated.
  • Pass: Deterministic startup and evidence-gated verification included.
  • Pass: Hydration treated as transitional, not end-state.

Project Structure​

Documentation (this feature)​

specs/001-baseline-uncontainerized-parity/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── fidelity-profile.md
├── quickstart.md
├── contracts/
│   ├── account-service/openapi.yaml
│   ├── people-service/openapi.yaml
│   ├── position-service/openapi.yaml
│   ├── reference-data/openapi.yaml
│   ├── trade-processor/openapi.yaml
│   └── trade-service/openapi.yaml
└── tasks.md

Source Code (repository root)​

pipeline/
scripts/
templates/
catalog/
generated/               # ephemeral output workspace (gitignored)
  ├── code/components/
  ├── code/target-generated/
  ├── manifests/
  └── api-docs/
.specify/
specs/

Structure Decision: Root .specify/ + specs/NNN-* are canonical, with generated runtime/code/docs outputs emitted under root generated/.

Complexity Tracking​

ViolationWhy NeededSimpler Alternative Rejected Because
Temporary coexistence of legacy TraderSpec/** notes with root-canonical workflowPreserve migration history and traceability during cleanupImmediate hard-delete would remove useful migration evidence before Phase C closure

Issue #461 implementation​

Keep H2 2.4.240 and replace literal allowed-value IN checks with equivalent CASE checks in baseline and pricing schemas. Centralize Spring after-commit publication in a helper retained by the state 004 generation hook and inherited by pricing. Capture booking event values before commit, contain notification failures separately per topic, and document the best-effort delivery limitation and existing-database migration. Exercise real H2/JPA commits, rollback, injected JDBC commit failure, connection retirement, and sequential accumulated positions in regression tests.

Dependency remediation (#465)​

Use public Boot 4.0.8 with its Framework 7.0.9/Data JPA 4.0.7 baseline and Tomcat 11.0.26; adapt Springdoc, Jackson messaging adapters, and removed HTTP status APIs in canonical templates and inherited patchsets. Refresh Node security overrides and lockfiles. Preserve #461 booking behavior, regenerate 002 then 004 sequentially, and verify builds, booking tests, repository gates, and fresh dependency/image scans before snapshot publication. See docs/operations/dependency-security-465.md for advisory evidence and release status.