# 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.