음성 재생과 운영 배포 정리

docs/decisions/backend-node-transition.md

@@ -0,0 +1,43 @@
+# Backend Node.js Transition Decision
+
+Date: 2026-06-28
+
+## Decision
+
+Vignette keeps the current Python/FastAPI backend for the near-term delivery path, but the replacement target for new replaceable backend infrastructure is Node.js.
+
+This is not a full rewrite approval. The migration path is contract-first and strangler-style:
+
+- Keep the FastAPI core while delivery-critical behavior is still being closed.
+- Move cross-runtime boundaries into explicit contracts before extracting services.
+- Prefer Node.js for new replaceable services or gateway implementations once the contract is stable.
+- Do not weaken existing fail-closed security, persona catalog, DB/RLS, audit, or PII masking behavior to make migration easier.
+
+## Rationale
+
+The project proposal and team capability point toward Node.js, but a direct Python-to-Node rewrite during the current schedule would add delivery and staffing risk. The safer path is to make Python replaceable by pinning the wire contracts first.
+
+## First Boundary
+
+The first implementation boundary is the engine gateway contract:
+
+- `POST /v1/generate`
+- `POST /v1/stream`
+- SSE events: `token`, `done`, `error`
+- request/response models owned by `apps/api/app/contracts/engine_gateway.py`
+
+Both the FastAPI engine client and the current Python engine gateway import this same contract. A future Node.js gateway must preserve these shapes.
+
+## Invariants
+
+- `/personas` normal state remains `source:"database", degraded:false`; `seed_fallback` is not normal.
+- Browser credentials and BFF session behavior stay unchanged.
+- RBAC, RLS, audit logging, and PII masking stay fail-closed.
+- OpenAPI generated frontend contracts stay current.
+- Existing ports and local/prod startup paths stay compatible until a service is deliberately replaced.
+
+## Next Refactor Candidates
+
+1. Split persona HTTP DTOs and mappers from `routes/personas.py` while preserving OpenAPI schema names.
+2. Split learner/review session read-model assembly from `routes/sessions.py`.
+3. Leave `admin.py` mapper cleanup for later because RBAC, audit, and RLS blast radius is larger.