Architecture decisions
ADR 0001: Stateless gateway-neutral service
- Status: Accepted
- Date: 2026-10-03
Context
Groundskeeper must initially integrate with Portkey without making Portkey's webhook envelope, lifecycle, or failure semantics the domain model. Low-latency evaluation must continue during control-plane and database outages.
Decision
Build a stateless Go modular monolith. Gateway adapters terminate external
protocols and translate to a canonical evaluation model. Gin is confined to the
HTTP transport and is served through net/http. The hot path evaluates only
against an installed immutable snapshot.
Consequences
- Portkey is replaceable and additional gateways do not fork detector logic.
- Evaluators scale horizontally and need no session affinity.
- Control-plane changes require complete snapshot compilation and activation.
- Multi-turn features need an explicit future state design rather than hidden process memory.