Skip to content

ADR-0028: One repository and one deployable per service — platform API gateways replace the composition hosts

Decision

This page records a decision and its status. A Proposed decision is not binding; an Accepted decision is binding on the Factory until amended or superseded.

  • Status: Accepted 2026-11-05 by the product owner (decisions D72–D73); decision D74 was derived while applying them and was accepted by the owner on 2026-11-05 (D80); decision 7 was added the same day (D79)
  • Date: 2026-11-05
  • Deciders: Dmitry Khaymov (product owner)
  • Tags: deployment, repositories, gateways, stores

Context

ADR-0016 gave every logical service a deployment granularity (decision D23): 19 services were standalone hosts and 48 were modules of a host, sharing the host's process and relational store. The intent was a small number of deployables for a pilot.

Planning the build backlog needs every work item to name the repository it changes. The owner decided how code is split and how it is deployed:

  • one repository per modelled service, as elsewhere in the ConnectSoft estate;
  • every service deploys alone, so co-hosting is dropped;
  • the composition hosts are kept as thin API gateways of their platforms.

Decision

  1. One repository and one deployable per service (D72). Each of the modelled Factory services is built in the repository ConnectSoft.AI.SoftwareFactory.<ServiceId> and ships as its own deployable. The deployment granularity module-of-host is retired; a modelled service is standalone. The two per-product representatives (GeneratedProductHost, GeneratedSaasFoundations) are examples of generated products and have no Factory repository.
  2. Platform API gateways (D73). The fourteen stateless composition hosts are re-scoped as the API gateways of their platforms, on the API gateway template: they route public REST and internal gRPC calls to the services they front, validate tokens and scopes, and own no business state. Their identifiers are kept so that links and references stay valid. StudioBff stays the backend-for-frontend of the Studio. Each service with the role service is fronted by exactly one gateway of its own platform.
  3. Single-entry rules move to the service. ModelRouterService is the only service that calls model providers and ToolAdapterService is the only service that executes tools; their gateways are the only routes to them (GW-04, GW-05).
  4. Agent Mesh. AgentRuntimeService and WorkflowEngineService deploy alone as two silo kinds of one Orleans cluster; AgentRuntimeWorker becomes the platform's internal gateway. The durable execution substrate of ADR-0024 does not change.
  5. A relational store per service (D74, derived, accepted by the owner). A service that deploys alone cannot share a database through a host. Each service owns one relational store; the thirteen platform stores are split into per-service stores, and the blob, vector and immutable audit stores are owned by the service that is their authority. A service binds only the relational store it owns. The shared cache and the event transport stay shared infrastructure.
  6. Model vocabulary. A service file carries repository, deployment.role (service, platform-gateway, bff, edge-service, representative) and, for a gateway, deployment.fronts. A registry row that was folded into a modelled service has the granularity merged and names merged_into. The validator enforces all of it.
  7. What a gateway keeps (D79). A platform gateway keeps its routing option, the identity authority it validates tokens against, protocol and transport exposure switches where it has them, request count and latency metrics, and three failure modes: the identity platform is unreachable, a fronted service is unavailable, a gateway replica crashes. Its libraries are the tenancy, resource-server, rate-limiting and observability libraries, and its only store is the shared cache. Every other option, metric, failure mode, library, component, secret and external dependency that a former host carried belongs to the service that owns the behaviour. Each service that publishes or consumes messages has its own messaging service name, its own transport credential and the Orleans messaging profile library, because its inbox and outbox are its own.

Consequences

  • The Factory has 65 repositories and deployables: 48 services, 14 platform gateways, the Studio BFF and two edge services. The first outcome (ADR-0027) touches about 27 of the services.
  • Infrastructure and operations cost rise: more pipelines, more container workloads, 48 relational stores in place of 13, and network hops where calls were in-process. This is accepted by the owner in exchange for independent ownership, release and scaling of every service.
  • Work that a host did once must be done per service: health and readiness, outbox and inbox, token validation, tenancy filters, telemetry wiring. The base template provides these; the build backlog carries a readiness feature for the shared conventions.
  • A transaction can no longer span two services of one platform. Where the model relied on one database for several modules, consistency is by events and the outbox, as it already is across platforms.
  • The fourteen gateway model files were rewritten to decision 7 and 47 service files received what their gateway had carried for them; the hand-written platform pages that described one modular host or a shared platform store were rewritten to this decision.
  • The granularity counts of the registry are now 67 standalone, 79 merged, 30 external-canonical and 15 later.

Alternatives rejected

  • One repository per deployable host with modules inside. Fewer repositories and deployables. Rejected by the owner in favour of one repository per service.
  • Service repositories that publish packages composed by host repositories. Keeps co-hosting with separate repositories. Rejected by the owner: every service deploys alone.
  • Retiring the composition hosts. Rejected by the owner: each platform keeps one API gateway.
  • Keeping the platform stores shared across separately deployed services. Rejected: it couples releases and schema ownership of services that no longer share a process.

Revisit triggers

  • Measured cost or latency of the separated services exceeds what a profile can carry: a profile may then co-locate services behind the same contracts.
  • A platform proves to need one transaction across two of its services: the two services are then merged, or the decision is reopened for that platform.
  • A gateway accumulates logic beyond routing and validation.

Amendment 2026-11-06: gateways consume no events; every service declares its replica range (D86, D92)

  1. A platform gateway consumes no events and is never listed as a consumer. An event travels from the service that publishes it to the service that handles it. The retention events (RetentionRuleChanged, LegalHoldChanged, DeletionOrderIssued) had named eight gateways as consumers, a remainder of the modular hosts; they now name the 30 services those gateways front, and each service declares its own handler for its own store. The validator reports a gateway consumer as an error.
  2. Every producer-listed consumer declares a consumes row. The 510 entries that had no handler have one: the Studio backend-for-frontend refreshes the view of the aggregate, AuditService records evidence, DashboardService updates the projection of the aggregate, and the other services name a handler for what they do with the event.
  3. Every service declares its replica range. A service that deploys alone carries deployment.runtime with a minimum and a maximum. The 47 services that had none take the range of the gateway that fronts them, which is the range their former host carried; it is a starting value and not a sizing.
  4. Objectives of named operations are model values. A service declares them under nfr.objectives; the Governance services and their gateway override the class availability with 99.9 %.

Amendment 2026-11-07: Factory services scaffold from the base template (D94)

A Factory service is scaffolded from the base template connectsoft-base (ConnectSoft.BaseTemplate), which carries the Clean Architecture project model, the service, persistence, messaging, actor and scheduler switches and the observability wiring the services need. The microservice template connectsoft-microservice is not used for Factory services. The 46 services that named it are rebound. Every other kind keeps the template of its kind: the platform gateways connectsoft-apigateway, the agent services AgentRuntimeService and WorkflowEngineService the agent template connectsoft-ai-agent (ConnectSoft.AI.SoftwareFactory.AgentTemplate), the generated SaaS representatives their SaaS templates, and the authorization server stays the existing component on connectsoft-authorization-server. The repository task of every service in the build backlog reads dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.<ServiceId>. Generated products are scaffolded from the base template as well (D95): the module outputs of the blueprint kinds and the worked examples name connectsoft-base. The build backlog carries the extensions the templates need before the first scaffold and the first generation (D96, features FEAT-153 to FEAT-160 of the epic Ecosystem component extensions): the agent host template first, then the base template and the API gateway template, and (D97, FEAT-161 to FEAT-166) the identity, authorization server and SaaS templates whose gaps the Factory needs closed before it resolves tenants, issues Factory tokens, exports usage and reads editions, and (D99, FEAT-167 to FEAT-170) the Blazor shell, microfrontend and UI kit templates before the Studio, and (D100, FEAT-171 to FEAT-174) the worker and health aggregator templates with their engine libraries, and (D102, FEAT-180 to FEAT-182) the API library template the gateway clients are generated from and the documentation template every repository's site is scaffolded from. The library template the contracts package, the gateway clients and every Backend Library module are scaffolded from, and the AI skills library template compiled skill packages are scaffolded from, follow (D103, FEAT-183 and FEAT-184). The platform template, which becomes the environment stack of an estate (baseline, per-service workload manifests, observability specification), and the marketing site template as a product module follow (D105, FEAT-185 and FEAT-186). The libraries the services share are extended rather than re-implemented per repository (D101, FEAT-175 to FEAT-179): observability conventions, the audit evidence record, the compliance data classes, typed gateway clients from the API library template, and MassTransit parity for generated products. Every such feature is marked before development and comes first in its increment (D98, ADR-0029).

Amendment 2026-11-11: the Factory profile switch (D114)

A Factory service, worker, gateway or library is scaffolded with the boolean template parameter UseFactoryProfile, off by default and named the same in every template that has a Factory shape, so other generations do not change: dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.<ServiceId> --UseFactoryProfile true. The shared template pipeline admits one additional gating case per declared profile beside the default case. The Factory feed is the Azure Artifacts feed the ConnectSoft libraries already publish to. Under the profile the processed-message key of a worker is scoped by tenant and project; the default worker keeps its key.

Amendment 2026-11-11: the Factory instance of the Identity Platform (D117)

The Factory owns the repositories of its own instance of the Identity Platform, scaffolded from the published templates like every other deployable: ConnectSoft.AI.SoftwareFactory.Identity from the Identity template and ConnectSoft.AI.SoftwareFactory.AuthorizationServer from the authorization server template, each with its pipeline and deployable.