Software Architecture

Purpose

The wiki describes the platform three ways, and each has its page: what the software is (this page — applications, libraries, plug-ins, schema, UI, infrastructure, one by one), what the agent framework provides to anyone who writes an agent (Agent Framework), and which agents exist and how they talk (Agents). This page is the first: every deployable and every library, its responsibility, its interfaces, its dependencies, and where its source comes from (§ 9). Nothing here is built yet; every row is P unless marked.

0. Solution placement [P, layout mirrors the proven AI module — F]

The platform is a module in serdica-backend, laid out exactly like Ablera.Serdica.AI on the codex/health-ai-csharp-architecture branch (own solution, App host, libraries, customer plugins, tests, per-module AGENTS.md):

src/Serdica/Ablera.Serdica.AI.Support/
  AGENTS.md                                     ← module guidance (estate convention: root AGENTS.md on master; 40 AGENTS.md on the AI branch)
  Ablera.Serdica.AI.Support.sln
  App/Ablera.Serdica.AI.Support.Webservice/     ← the host: Program, Endpoints, Runtime, Governance
  __Libraries/
    Ablera.Serdica.AI.Support.Persistence/      ← SRD_SUPPORT schema: versioned DbScripts, stores, retention
    Ablera.Serdica.AI.Support.Sessions/         ← case/session/task state machines
    Ablera.Serdica.AI.Support.Connectors.*/     ← one library per external system (tools)
  __Plugins/                                    ← customer-specific packs (Bulstrad skills, prompt catalogs)
  test/

1. The component map

flowchart TB
  UI["Operator and client UI"]:::owner
  API["Webservice API
HTTP and SignalR"]:::work
  RT["Durable runtime
scheduler and workers"]:::work
  MD["Model adapter
IInferenceClient"]:::work
  MEM["Profiles, skills
and owned knowledge"]:::learn
  G["Authority and audit"]:::decision
  EX["Deterministic executor
connector adapters"]:::work
  DB["Platform records
SRD_SUPPORT and papers"]:::store
  Q["Inbox and outbox
Rabbit delivery"]:::store
  T["Customer systems
and external owners"]:::store
  P["Customer plug-in
scope and domain bindings"]:::store
  UI --> API
  API --> RT
  P -.->|"bind at startup"| RT
  RT -->|"one model turn"| MD
  MEM -->|"pinned versions"| RT
  RT -->|"commit state"| DB
  RT -->|"durable messages"| Q
  RT -->|"proposed effects"| G
  G -->|"exact permit"| EX
  EX -->|"apply and verify"| T
  classDef work fill:#eef4ff,stroke:#6889ba,color:#17365b,stroke-width:1.3px
  classDef decision fill:#fff4df,stroke:#b78c36,color:#65470d,stroke-width:1.5px
  classDef proof fill:#e9f5ef,stroke:#689b81,color:#224e39,stroke-width:1.3px
  classDef learn fill:#f1edf9,stroke:#9580b9,color:#534172,stroke-width:1.3px
  classDef store fill:#f5f7fa,stroke:#98a6b7,color:#34445a,stroke-width:1.2px
  classDef owner fill:#24486b,stroke:#24486b,color:#ffffff,stroke-width:1.4px
  click UI href "ui.html" "The existing two surfaces use HTTP and committed realtime projections."
  click API href "contracts/openapi.yaml.html" "One API validates identity, commands and concurrency."
  click RT href "50-agents/agent-runtime.html" "One deployable image, with API and worker roles."
  click MD href "50-agents/model-execution.html" "An LLM proposes typed actions; the owned adapter is replaceable."
  click MEM href "50-agents/agent-framework.html" "Versioned authoring, memory and evaluation."
  click G href "gating.html" "The auditor reviews; gates and grants control target effects."
  click EX href "contracts/Connectors.Abstractions.cs.html" "Only registered, granted operations reach target systems."
  click DB href "data-model.html" "Durable tasks, call journal, decisions, evidence and immutable request bytes."
  click Q href "50-agents/agent-runtime.html" "Deduplicate messages and recover without replaying successful effects."
  click T href "trust-and-data.html" "Target estate is separate from platform persistence; owner work returns evidence."
  click P href "whitelabel-catalogue.html" "Channels, target capabilities, product vocabulary and customer policy."

Runtime responsibilities, not a project dependency graph. The library table below owns code dependencies and reuse choices. Target databases are deliberately separate from platform state.

2. Applications

P There is no separate worker application: a worker is the same image with a different role flag, so one Dockerfile, one CI job, one compose unit with two service entries.

3. Libraries — ours

P Ownership exposed by the case journeys: AI.Support.Sessions evaluates the execution-obligation join and scoped external responses through ports in AI.Support.Contracts; Papers supplies immutable revisions, Connectors supplies effect evidence and Memory supplies versioned applicability/use records. Runtime schedules external waits, restoration and post-result tasks through the same durable machinery. This adds no family-specific service or scheduler. UI projections read case papers and events; an LLM verdict cannot directly set resolved.

P Schema scope aliases. Names such as oracle-iprod, oracle-sys and oracle-integr in stage inventories denote scoped Oracle operations/credentials, not a requirement to build three additional driver libraries. The connector registry resolves them to the appropriate Oracle handler and explicit schema/environment scope. An unregistered alias is refused, never reflected into a class name.

4. Libraries — copied and linked

5. Plug-ins

6. Data

7. Cross-cutting

7.1 What the provider seam can normalise, and what it cannot P

The route seam makes a provider swappable; it does not make providers equivalent, and pretending otherwise is how a working case regresses on a different route. Stated so the limits are designed for rather than discovered:

⚠ The last row is the one that turns into an incident. A route change is a behaviour change, so it is a governed decision per profile (Agents § 0.3), not a deployment convenience.

8. Dependency rules P

P This is the compile-time dependency graph. Responsibilities in § 3 are logical collaborations, not ProjectReference edges. AI.Support.Contracts is the small owned library for case/task DTOs, unit-of-work/store ports, catalogue readers, execution/evaluation ports and notifications. Copied AI.Contracts supplies canonical JSON, hashes and scalar primitives.

P The host opens a unit of work for each platform transition and passes it through store/ledger/outbox ports. No store commits behind its caller. A scoped DbContext can implement that unit of work, but neither context nor transaction crosses a model call, target call or human wait.

P AgentExecutionContext exposes an explicit filtered tool/reader facade. Standard .NET child scopes share registrations; they are not capability subtraction. A model receives neither IServiceProvider nor credentials. The connector resolves credentials from a persisted execution permit and rechecks scope. See Runtime § 3.

P Customer table names, endpoint conventions and source layouts are plug-in/shape data, not runtime switches. Closed protocol states are versioned software contracts; business case types, stage outcomes, profiles and policies remain data. Copied projects are owned here; no ProjectReference points into the unmerged health module.

9. Reuse — the map and the verdicts

Name, source, or nothing — per project (decision 02.09.2026): the branch is not merged and nothing is linked from it. Contracts, abstractions, the Azure OpenAI adapter, the Rabbit integration/outbox libraries and a handful of Manager classes are copied into the module; Persistence, Metering, Prompting, the governance and runtime services and the host are name-only (their conventions re-implemented over SRD_SUPPORT); the Workflow/StellaOps tree, File Server V2 and the health plug-ins are nothing; Microservice.Rpc, Workflow.Tasks, Authority and the host plumbing are linked from the estate's own master/bulstrad-qa, where they exist; RabbitMQ.Client/.Topology are copied from the health branch and owned (D48; T2 GIT-6). The full table with evidence: § 9. ⚠ bulstrad-staging and bulstrad-prod run the old source layout without any of those libraries — which is why the platform is deployed on QA and reaches the other environments through connectors (Software Architecture § 10.1).

F Placement is not blocked (verified 01.09.2026). D-P2 — "Ablera.Serdica.AI.Manager is the only Serdica AI runtime deployable" (00-program.md:18) — is prose, not enforcement: src/Serdica/Ablera.Serdica.AI has zero files on master, bulstrad-qa, bulstrad-staging and bulstrad-prod, existing only on the unmerged health branch, and the one code-level guard asserts a single deployable inside that module's own tree, which a sibling in src/Serdica/ does not touch. § 1's layout stands. P The wording is accepted as-is (Vladimir owns the health-AI program — D27-a, D41 of 02.09.2026); a one-line rewording — "one AI runtime host per module; AI.Manager is the health module's" — is queued for the next time the health branch is touched. No rename; the AI_MANAGER wire vocabulary stays. The health-AI branch codex/health-ai-csharp-architecture will not be merged (decision 02.09.2026). Nothing is linked from it. For every project the verdict is one of three: name-only (take the naming and the convention, write our own), copy-source (copy the files into the AI.Support module and own them), or nothing. Projects that exist on master/bulstrad-qa are linked from the estate itself, not from the branch. Inventory taken 02.09.2026 by read-only git over the branch and the four estate branches; every row names its evidence.

P This inventory is the selection, not a survey (decision Vladimir, 02.09.2026 — D62). The platform needs the capabilities in § 1–3 regardless of where they come from — the question is only which source serves each one best, and each row below is that judgment, made now, with its evidence attached. Rules of the selection: a copied library is ours from the day it lands — versioned with the module, no upstream tracking, no ProjectReference back into the branch; a name-only capability is re-implemented over SRD_SUPPORT to the stated convention; a linked library is taken from the estate's own master/bulstrad-qa line, never from the branch. Adding a library later means adding a row here with the same three-way verdict and evidence — not a reference appearing in a .csproj first.

9.0 The fact that shapes every verdict — two source layouts F

Consequence: "already in the estate" means the QA line. The platform's development target is Bulstrad QA (Software Architecture), so every link-as-is verdict below holds there; the customer-facing STAGING/PROD lineage has none of the new-layout libraries. The platform does not need to be deployed on STAGING or PROD to work their tickets — it needs connector reach to them (§ 10.3) — so the split is a constraint on where the platform runs, not on what it can touch.

9.1 Copy-source — small, decoupled, and we own it afterwards P

9.2 Name-only — the convention is ours to re-implement P

9.3 Link as-is — present in the estate on the QA line F

9.4 Nothing P

9.5 What the branch never had F

No Dockerfile and no build/push CI job exist for Ablera.Serdica.AI.Manager or FileServer.V2 on the branch; only Workflow plug-ins gained CI, plus three test/doc jobs. The branch is 605 commits behind master (last commit 17.08.2026). Its infrastructure design (docs/architecture/health-ai/17-infrastructure.md) is nevertheless the best written description of the estate's deployment mechanics and is the source for Software Architecture § 10.2.

10. Hosting and operations

A platform that reads production tickets, queries production databases and writes to them under a gate has to run somewhere with some identity, reached over some network, operated by someone. None of that was written down before 02.09.2026. This page fixes what the repository and the estate's memory establish, decides what can be decided now, and names the questions only Bulstrad IT or Ablera DevOps can answer. Evidence base: the repository inventory of 02.09.2026 (§ 9), .gitlab-ci/* on bulstrad-staging and master, the health-AI infrastructure design (docs/architecture/health-ai/17-infrastructure.md on the unmerged branch), and the estate memories linked inline.

10.1 Where it runs P

P Operational responsibility. This is the production control service even though its host is named QA. API/worker, broker, Oracle metadata, papers and key service form its operational dependency set. Before real writes, prove backup/restore, off-database export, kill switch and reconciliation. A ledger export alone cannot restore paper bytes, keys or unknown target effects. The dated measurements below are the known baseline, not a current restore test.

The platform is one deployment, on the Bulstrad QA environment, and it works every environment from there. It does not get promoted to STAGING or PROD as a service; its connectors reach STAGING and PROD databases and systems over the network, exactly as v1 operators do today from laptops over VPN (Baseline § 1).

P The control plane's placement is itself configuration (decision Vladimir, 02.09.2026 — D63): which environment hosts the platform, and which environment a case starts from, are plug-in values (platform.host, source.start_flows — Whitelabel Catalogue § 4), never code. The Bulstrad defaults are below; a second customer names its own host and flows. Per case type — and, since D123, per product line, for the Configuration module's working environment as much as for the Development module's start — the environment differs by design: new, unreleased products (the health line) start on QA, their work is backported to master, and their production target is the planned bulstrad-prod-2; running products start on bulstrad-staging and the fix then travels to master and bulstrad-qa (Development Details DG-2).

Why QA and not Ablera DEV: the PL/SQL developer works on QA, the customer's branches are bulstrad-*, the product data is the customer's, and the identity provider there is Authority, which the platform reuses. Why not STAGING or PROD: those run the old source layout without src/__Libraries, Authority or McpProxy (Software Architecture § 9.0); deploying the platform there would mean packaging every library as NuGet for a lineage that is about to receive the new layout anyway. The platform does not need to live there to work there.

10.2 How it is built and deployed F

The estate's mechanism, unchanged:

1. Build — GitLab CI on a shell-docker runner runs docker buildx build per service from a Dockerfile at src/Serdica/<Module>/<Service>.Dockerfile, tags ${CI_REGISTRY_IMAGE}/<service>:<branch>_TEMP-<pipeline> into registry.ablera.dev (templates/build-job.yml@bulstrad-staging:14-78). The CI file per service is generated by tools/Ablera.Serdica.CiJobsBuilder on the new layout (.gitlab-ci/autogenerated/microservices/*.yml@master); P its invocation has no README — read Program.cs before generating.
2. Push — on a bulstrad-* branch the image is re-tagged bulstrad-registry.ablera.dev/<service>:<branch> (templates/push-job.yml:14-51), so the tag QA pulls is bulstrad-qa.
3. Deploy — a manual job runs the registry.ablera.dev/ablera/serdica-infrastructure:1.0.0 Ansible image over SSH to the VM with Vault secrets (templates/deploy-job.yml:1-31). The playbooks, docker-compose.<unit>.yml files, vars.<env>.j2 and nginx templates live in the separate serdica-infrastructure repository; the Bulstrad deploy jobs are not in serdica-backend — P the trigger is a rule for the deployment agent (D130): the last build job of serdica-infrastructure, then the deployment-phase job that includes the service (the .yml files name it); bulstrad-staging and bulstrad-prod come from the v3.0.0 branch with their own compose files, master and the rest from master.
4. Configure — per-branch appsettings.json overridden by SERDICA_* environment variables; secrets come from HashiCorp Vault (vault.ablera.dev) at deploy time only, containers never see VAULT_TOKEN (17-infrastructure.md:96; branch memory).
5. Register — the service declares MicroserviceConfig (exchange ai_support, queue ai_support.request) and writes its SRD_SYS."EndpointSections" rows at start-up through Microservice.Initializer.EndpointsRegistration (service topology).
6. DDL — DbScripts/SrdSupport/NNN-*.sql + install-clean / upgrade / grant-runtime; the write executor applies it under the HW-ddl gate with the identity of the current D65 stage (D104).

P What the module adds to the repository: the project tree of Software Architecture § 0, one Dockerfile, the generated CI file listing every src/__Libraries/* dependency, appsettings.json per branch with everything disabled by default (the health-AI convention: AcceptActivities: false until the environment enables it), and the DbScripts. What it adds to serdica-infrastructure: the compose unit, vars.<env>.j2 entries, Vault secrets (DB_URL_AI_SUPPORT, provider keys, connector credentials), a deploy_serdica_ai_support job, an nginx location.

10.3 Network reach — the connectors' world P

P Reach is a platform capability, not a network request (decision Vladimir, 02.09.2026 — D46), and every connection is direct (decision Vladimir, 04.09.2026 — D132): the platform brings a probe, not a tunnel. Each target's reach — direct or unreachable from this deployment — is data per environment in CONNECTOR_SCOPES rows of kind reach (target {host, port, paths}, route {kind: direct|unreachable}, modes, credential_ref, health, verified; unverified addresses such as 10.239.82.108/.101 are refused for writes — Challenge Rounds § R2 § 9). The v1 paths already exist as direct paths: TNS to the databases, HTTPS to Jira/Graph/HDesk/GitLab, SSH to the Linux hosts; the v1 SSH tunnel through a Bulstrad server to the SOA host (BI Publisher, ЕИСОУКР, GetKATData — memory) is not carried over — those targets are reached directly or the case parks on a capability gap and the missing route becomes a specific, defendable request to the estate's network (D128), whose answer changes a row. Model calls go directly from the QA host to the provider's EU endpoint; there is no Ablera-side model gateway in the design. The remaining request to Bulstrad IT is therefore network only — the roles need no directory change (D134, § 10.4).

10.4 Identities and service accounts P

The PC agent's named gap — the write path ran under a personal session (Product Configurator § P) — is closed here, or the platform is v1 with a web page.

10.5 Who operates what [F → P]

P The minimum alert set (D66) — the platform raises, into the estate's existing log alert channel (Kibana over fluentd.bst-qa-env): ledger seal/export lag beyond one interval (Architecture § 3.2) · connector health red per environment × system · budget hard-stops per case · gate escalation past its first interval (PG-12) · eval set red at publish · parked-case age past the case type's threshold · kill switch flipped (either mode). An alert is a ledger event first, so the operations view and the metrics read the same facts.

F QA has no working backup (measured 02.09.2026, Measurements § DB § 5–6): last RMAN job 26.07.2024, FAILED; NOARCHIVELOG; flashback off; no restore points; undo 900 s NOGUARANTEE; USERS tablespace 48 of 48 GB with 8.4 GB free; no SRD_SUPPORT user (verified 03.09.2026); unified auditing off and no statement audit options; 19c Enterprise Edition. STAGING is backed up nightly (also NOARCHIVELOG); PROD is ARCHIVELOG with completed backups. P The request to the Bulstrad DBA is therefore not "confirm SRD_SUPPORT is in the inventory" but: restore QA backups, switch QA to ARCHIVELOG, create the single SRD_SUPPORT user with its own autoextend tablespace and a profile with a SESSIONS_PER_USER cap (Ablera's DBA — D47), and enable a unified-audit policy on CREATE/ALTER PACKAGE for SRD_INTEGR. Until then the PL/SQL git mirror (Stage Planning § 3b) is the only durable copy of anything on QA, and the ledger's RPO on QA is undefined; all nfr.targets durability values are conditional on D45 restoring the QA backup path first.

10.6 Environments of the platform itself P

The platform has one production instance (on QA, as above) and a developer instance on an Ablera developer machine, run the way the health-AI rig runs qa-connected: the service local, connected over VPN to the QA database, broker and Redis. Eval sets and replay tests (Agent Runtime § 9.2 patterns 18–19) run on the developer instance and in CI against recorded sessions; nothing in CI touches a Bulstrad database.

10.7 Actions with owners P

Decided 02.09.2026 (D45–D48); listed here so the text is not lost and the owner is named.

Challenges

• P Memory store P (Challenge Rounds § R2 § 5): git is the store, Oracle the projection. Repository aisa-memory on the QA host volume, mirrored to GitLab by push; one file per article with frontmatter {id, version, state, owner_profile, provenance[], verify{}} — states are commits; SRD_SUPPORT.MEMORY_ARTICLES is an index rebuildable from the repository (commit first, row second; reconciled at start). Reasons: articles are immutable and versioned, retrieval is measured over bodies, and QA has no valid backup, so the mirrored repository is the durable copy that Oracle CLOBs would not be. Confirmed when: wave 1: every row's git_sha resolves; a rebuild from frontmatter shows zero differences.
• P Handles table P (same source): CASE_HANDLES stays in SRD_SUPPORT (D47 — one schema) and the boundary is cryptographic: value_enc is AES-GCM under a per-case data key wrapped by a Vault transit key, so Oracle, its backups and a DBA's SELECT * hold ciphertext; re-identification decrypts inside the connector process with a REIDENTIFY ledger event; destruction at the customer's closure deletes the rows and the key — crypto-shredding, so backup copies die too. Confirmed when: the data-boundary fixture: ten identifiers → zero plaintext outside WRITE_LOG.statement.
• P RabbitMQ.Client delta — settled (D48): the branch's RabbitMQ.Client, .Topology, .Integration and .Outbox are copied as library projects into the module; whether master later adopts the same delta is the library owner's matter, not the platform's.
• P Which targets are reachable directly from the QA host — resolved 04.09.2026 (D132, A-8): there is no tunnel and no via host — a target the probe cannot reach directly is a specific, defendable request to the customer's network (host, port, purpose) — never wildcard access — whose answer changes CONNECTOR_SCOPES rows, not code (D128, D46). P The platform's SSH account on the Linux hosts is the estate's deployment user (D129).
• F Hygiene: the BI Publisher credentials were stored in plaintext in knowledge/policy_print_recipe.md; redacted 02.09.2026 to a ${BIP_PASSWORD} reference — the value belongs in Vault.
• P The Bulstrad deploy trigger lives in serdica-infrastructure and is resolved by rule (D130): the last build job of the project, then the deployment-phase job that includes the service; bulstrad-staging and bulstrad-prod from the v3.0.0 branch, the rest from master. The compose unit for the platform itself is still Ablera DevOps' to add.
• P 10.239.82.108 is both the PROD compose host (CI variables) and the OSB/SOA facade in service topology — one host or a stale record; 10.239.82.101 is "bulstrad-on-prem" in CI and the decommissioned old TEST in memory — whether on-prem is live is unknown. Neither affects the QA placement; both affect the connector address book.
• P OpenTelemetry sink — none exists in the estate; first target the existing Elasticsearch or add a collector to the compose unit.

P Provider implementation detail. Model Execution records the inspected copy source and structured-action loop over IInferenceClient. The copied adapter is one inference call; native tool calling and durable orchestration are not assumed to exist in it.