adam/proposal-system
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/proposal-system.git synced 2026-09-30 07:43:14 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
proposal-system/docs/adr/0002-shoc-merge-boundary.md
Adam Moussa a4b09eb0ad
docs: SHOC-alignment Phase 1 — ADRs, governance files, doc corrections (#220) 
- Add ADR 0002 (SHOC merge boundary: separate backend services, shared
  conventions) and ADR 0003 (adopt SHOC design system + UI/UX layout)
- Add CODEOWNERS (internal-dev) and PR template (Summary/Test plan/Jira/
  docs-current checklist + contract-table convention)
- Fix stale facts in README/CLAUDE.md: MUI v7→v9, RN 0.85→0.86,
  OpenSearch Serverless/oss-index-creator → Aurora pgvector/
  aurora-pgvector-init (ADR 0001), test counts 149→186 (123 xUnit /
  26 vitest / 37 pytest), deploy triggers are workflow_dispatch-only,
  reusable workflow refs float on @main, aws-cdk-lib version claim
  replaced with Dependabot-maintained note
2026-07-13 17:00:45 -04:00

3.2 KiB
Raw Blame History

ADR 0002 — SHOC merge boundary: separate backend services, shared conventions

  • Status: Accepted (2026-07-13)
  • Decision owner: Adam Moussa
  • Scope: proposal-system ↔ SHOC (shoc-backend / shoc-frontend-new) consolidation strategy

Context

proposal-system was built as a standalone service deliberately mirroring SHOC's architecture for a clean future merge. As of 2026-07-13 the two projects diverge on platform fundamentals:

Axis proposal-system SHOC
Database Aurora PostgreSQL (pgvector) via EF Core/Npgsql SQL Server via EF Core
Identity Cognito (hosted UI, groups, web + mobile clients) ASP.NET Identity + custom JWT issuance
API layout 4-project Clean Architecture (Api/Application/Infrastructure/Domain) Single API project, services injecting DbContext
Error contract RFC 7807 ProblemDetails, string enums Typed-exception codes per controller, numeric enums
Hosting Lambda behind API Gateway (CDK) Elastic Beanstalk (external-dev account)

A full platform alignment (engine migration, auth migration, rehosting) would cost weeks, carry data-migration risk, and deliver no user value.

Decision

The backends remain separate services permanently. Consolidation converges on conventions, layers, and service patterns — never on platform.

Concretely:

  1. No database engine migration in either direction. PostgreSQL stays here; SQL Server stays in SHOC.
  2. No identity migration now. Cognito stays here. At consolidation time, identity converges on Cognito (or a federation layer in front of both) — not on ASP.NET Identity, which would regress to self-managed credentials and reintroduce the remediated WEB-C1 token-theft class (SHOC currently stores JWTs in localStorage).
  3. Conventions converge (tracked by the 2026-07 SHOC-alignment plan):
    • Frontend: SHOC's design system + UI/UX layout (ADR 0003), domain layering (src/domain/<entity>/{api,schemas,mappers,types,use-cases}), TanStack Query, zod, react-hook-form.
    • API contracts: shared TypeScript contracts package + zod schemas; ProblemDetails with machine-readable business code extensions (SHOC's error-code vocabulary, proposal-system's envelope).
    • Mutation semantics: optimistic concurrency with SHOC's 409-plus-currentState response shape; staged audit-trail entries persisted at one SaveChanges boundary.
    • Process: org reusable CI callers, CODEOWNERS, PR template, conventional commits.
  4. Layering stays Clean Architecture here. SHOC's flatter service style is not adopted; if SHOC restructures at consolidation, this repo's 4-project layout is the reference shape.

Consequences

  • The eventual "merge" is a monorepo consolidation of independently deployable services sharing a frontend architecture and wire conventions — not a single backend.
  • A merged frontend can treat both APIs identically for errors (ProblemDetails + code) and conflicts (409 + currentState) once alignment phases 3/6 land.
  • Anything requiring one database across both domains (cross-domain reporting, shared entities) must go through APIs, not shared tables.
  • SHOC's localStorage JWT + CORS * are flagged to the SHOC team as findings; they are not constraints on this repo.