docs(adr-0024): ai service relay — gRPC dial + SSE bridge + POC principal

Proposes the integration contract between portal-bff and apf-ai-service: - BFF dials the AI service over native gRPC HTTP/2 (h2c in dev, h2 + TLS in prod) via @grpc/grpc-js + ts-proto stubs. - Browser-facing chat surface is text/event-stream — each ChatEvent oneof case translates to one SSE frame; cancellation flows browser-close → call.cancel() → upstream LLM stop. - Proto files vendored from apf-ai-service/contract/proto into the BFF with on-demand codegen; both proto + generated stubs committed for hermetic builds and reviewable diffs. - POC ships unsigned Principal { subject, roles[], attributes{} } in the proto body, mirroring apf-ai-service's ADR-0010. Subject is the Entra oid hashed with the same HashUserIdService salt as the audit module so apf_portal and apf-ai-service audit trails join cleanly. - Production hardening choice (signed envelope vs mTLS) deferred until the first production deployment is in scope; recorded as an open item to be amended jointly in both repos.
2026-05-19 19:52:42 +02:00
parent 40d4f7d290
commit 01fe01ffe7
2 changed files with 333 additions and 0 deletions
@@ -67,3 +67,4 @@ ADRs are listed in numerical order. To slice by topic, filter on the `Tags` colu
 | [0021](0021-phase-2-security-baseline.md)                    | Phase-2 security baseline — helmet, CORS allowlist, double-submit CSRF, rate limiting, structured error envelope | accepted | `security`, `backend`                                          | 2026-05-13 |
 | [0022](0022-docs-site-vitepress.md)                          | Documentation site — VitePress + Mermaid plugin, separate static deployment                                      | accepted | `process`, `infrastructure`                                    | 2026-05-15 |
 | [0023](0023-charts-d3-observable-plot.md)                    | Charts + dashboards — D3 + Observable Plot wrapped in `libs/shared/charts`                                       | accepted | `frontend`, `accessibility`, `performance`                     | 2026-05-16 |
+| [0024](0024-ai-service-relay-grpc-sse-bridge.md)             | AI service relay — vendored gRPC protos, NestJS gRPC client, SSE bridge to the SPA, POC unsigned principal       | proposed | `backend`, `security`, `observability`                         | 2026-05-19 |