Platform Solution Design Specification

0. Purpose, Scope, and Reading Order

This document provides the solution design for a software platform built around the LATTICE ontology stack and MORK mapping pipeline, explaining the various control planes, worker process tier, message and data infrastructure, multiple web applications, and release management approach.

Supplementary Documents

• ADRs docs/architecture/decisions A29 through A43 record individual boundary decisions as they were made.
• Inter-component data contracts are specified under contracts/ and say what JSON moves between components
• Ontology design and layer semantics, DL encodings, and layer dependency rules stay in the layer READMEs and in ontology-architecture.md.
• UX specification in full, in ux-design.md
• Data model in data-architecture.md
• RDF Patterns in rdf-sparql-patterns-guide.md

This platform architecture ties all of those together, and is the primary entry point for a reader new to the codebase.

Status discipline.

This document is maintained as a living design record, alongside the ADR catalogue.Every decision below is marked as one of:

• Established — already decided and implemented, cited to its ADR or code.
• Decided here — a genuine gap this document closes for the first time. Flagged in §8 as a candidate for a formal ADR.
• Deferred — explicitly out of scope, with the reason stated once.

Document map

Read this document top to bottom once, then use it as a reference.

Solution Overview

There are 2 very distinct sides to LATTICE. The first is the “BUILD TIME” or “DESIGN TIME” platform, which is basically a set of react applications and other tools, glued together with various software services, messaging infrastructure, graph database(s), etc. This is a deployable system with many moving parts - it is something we (in this repo) are building and design and WE get to DECIDE how it works.

Then there is the other side of LATTICE - “PRODUCTION TIME”, and that is where things are completely different. We do not own, define, or even know what “PRODUCTION” looks like! It will be different for everyone that builds on LATTICE. Perhaps someone will just use the ontologies and never touch the design-time application suite. Perhaps someone will use the full design-time suite to build their graph and configuration, but once it is populated, just use MORK as an integration layer, or maybe they use something else to pull data in and just use surface for making skos vocabularies available via entailment. We simply don’t know what they will do, all we know is it will be code in another repo!

We cannot decide which patterns are right for this 2nd use of LATTICE, because it is not an application we own. Multiple agent outputs have mentioned “multi-tenant”, but LATTICE is not that kind of platform - though you could use it to build such a thing, I hope.

We will need to design a means for these users (who are building on top of lattice ontologies and perhaps re-using lattice services) to declaratively choose the patterns they want to use as configuration - perhaps this can be another dimension of surface (see the repository).

Yes, we might write a query layer that automatically applies the separate version/identification/sequencing behaviour so the user doesn’t need to think about it - but we do that by building a compiler, a query generatory/optimiser, and only then write the layer that uses those things and let the consumer decide if they want the pattern, the tools, the APIs, or the full stack for their app.

1. Technical Capability Catalogue

2. Process Design

2.1 Actor Inventory

Human actors

System actors

2.2 The Sync/Async Boundary Rule

Established as a design rule here, consistent with existing code. A request is synchronous when it only needs a single transaction to answer (e.g., a PostgreSQL read/write). A request is asynchronous when its duration is not bounded by a database round trip. | Operation class | Sync or async | Why | |—|—|—| | Create/read/transition a Surface revision | Sync | Single-row read, optimistic-concurrency write, no external I/O | | Register a graph-family artifact | Sync | Single-row insert with a uniqueness check | | Generation, parity, invalidation | Async | Requires materializing graphs from Fuseki and running the compiler | | Projection lowering | Async | Same reason | | MORK analysis | Async | Requires reading the mapping graph and running validation/community analysis | | Semantic release assembly (plan) | Sync | Pure evidence verification against already-recorded data | | Release packaging (publish) | Async from the caller’s perspective, because it performs file I/O and optional signing, but implemented as a request-triggered background operation, not a broker job (see §4.4) | | MORK review decision recording | Sync | Single-row write against an immutable snapshot hash | | MORK bulk confirmation | Sync per item, gated by a synchronously checked calibration read | The gate check must complete before any item is confirmed |

2.3 Reliability Mechanisms at Actor Boundaries

2.4 Process Maps

Each map states its participants, trigger, and explicit sync/async boundary. Solid arrows are synchronous request/response. Dashed arrows are asynchronous message flow.

P1 — Surface Contract Authoring and Lifecycle

sequenceDiagram
    actor Author
    actor Reviewer as Reviewer/Approver
    participant Studio as Surface Contract Studio
    participant CP as Control Plane (Surface API)
    participant PG as PostgreSQL

    Author->>Studio: edit contract fields
    Studio->>CP: POST /surface/revisions (draft)
    CP->>PG: insert surface_revision_ledger (version 0)
    PG-->>CP: created
    CP-->>Studio: 201 VersionedSurfaceRevision
    Author->>Studio: request review
    Studio->>CP: POST /transitions {expectedVersion, REQUEST_REVIEW}
    CP->>PG: compare-and-set on version
    alt version matches
        PG-->>CP: updated, version+1
        CP-->>Studio: 200
    else version stale
        PG-->>CP: no row matched
        CP-->>Studio: 409 stale revision
        Studio-->>Author: show conflict, reload current state
    end
    Reviewer->>Studio: approve (approvalId)
    Studio->>CP: POST /transitions {expectedVersion, APPROVE, approvalId}
    CP->>PG: compare-and-set
    PG-->>CP: updated
    CP-->>Studio: 200 state=APPROVED

All of P1 is synchronous. No message is published until generation is requested (P2).

P2 — Surface Generation Job Execution

sequenceDiagram
    actor Reviewer as Reviewer/Approver
    participant Studio
    participant CP as Control Plane
    participant PG as PostgreSQL
    participant MQ as RabbitMQ
    participant W as Surface Worker
    participant Fuseki

    Reviewer->>Studio: request generation
    Studio->>CP: POST /transitions {RECORD_GENERATION intent}
    CP->>PG: begin transaction
    CP->>PG: write job_status = PENDING
    CP->>PG: write outbox row (same transaction)
    CP->>PG: commit
    CP-->>Studio: 202 jobId
    par relay
        CP->>MQ: publish surface-job-request (from outbox)
    and worker loop
        MQ-->>W: deliver (manual ack pending)
    end
    W->>Fuseki: fetch contract, profile, source graphs
    Fuseki-->>W: canonical bytes
    W->>W: verify SHA-256 against revisionHash
    W->>W: run compiler (compile --verify-determinism --parity)
    W->>Fuseki: publish generated output graph (immutable)
    W->>MQ: publish surface-job-result
    MQ-->>CP: deliver result (manual ack pending)
    CP->>PG: idempotent record by jobId, update job_status
    CP->>MQ: ack
    loop poll
        Studio->>CP: GET /surface/jobs/{jobId}
        CP-->>Studio: status (pending/running/succeeded/failed)
    end

Everything from “publish surface-job-request” to “publish surface-job-result” is asynchronous. The Studio never blocks on it, it polls.

P3 — Surface Release Assembly and Packaging

This directly answers the release-integration exposure question. Full rationale is in §4.4.

sequenceDiagram
    actor Operator as Release Operator
    participant Studio as Studio (Release view)
    participant CP as Control Plane (Release facade)
    participant Assembly as SemanticReleaseAssemblyService
    participant Ledger as ReleaseLedger (PostgreSQL)
    participant Adapter as OciLayoutReleaseAdapter
    participant Artifacts as Artifact store
    participant Fuseki as Fuseki (provenance graph)

    Operator->>Studio: open release view for a GENERATED revision
    Studio->>CP: GET /release/candidates?revisionId=...
    CP-->>Studio: gate evidence summary
    Operator->>Studio: click Publish
    Studio->>CP: POST /release/candidates/{id}/publish
    CP->>Assembly: assemble(intent) [in-process call, same JVM]
    alt required gate missing
        Assembly-->>CP: rejected, named missing gate
        CP-->>Studio: 422 with missing gate
    else all gates present
        Assembly-->>CP: validated ReleaseIntent
        CP->>Ledger: recordIntent (transaction)
        CP->>Adapter: publish(intent) [in-process call]
        Adapter->>Artifacts: write OCI layout, blobs, manifest
        Adapter-->>CP: ReleaseReceipt (digest-addressed)
        CP->>Ledger: recordReceipt (requires prior intent)
        CP->>Fuseki: write provenance N-Triples to provenance graph
        CP-->>Studio: 200 ReleaseReceipt
    end
    Operator->>Studio: view release ledger
    Studio->>CP: GET /release/ledger/{releaseId}
    CP-->>Studio: ordered ledger events

SemanticReleaseAssemblyService, ReleaseLedger, and OciLayoutReleaseAdapter are called in-process by the Control Plane. They are a library, not a separate network service. See §4.4 for why, and for what remains external.

P4 — Surface Projection Lowering to MORK Staging

sequenceDiagram
    actor Author
    participant Studio
    participant CP as Control Plane
    participant MQ as RabbitMQ
    participant W as Projection Lowering Worker
    participant Fuseki

    Author->>Studio: request Projection lowering
    Studio->>CP: POST /projection/lower {contractGraph, profileGraph, stagingNamespace}
    CP->>MQ: enqueue (via outbox)
    MQ-->>W: deliver
    W->>Fuseki: materialize contract and profile
    W->>W: validate deterministic-only, no LLM completion policy
    W->>Fuseki: write immutable MORK staging graph (content-addressed)
    W->>MQ: publish projection-lower-result
    MQ-->>CP: deliver, idempotent record
    Studio->>CP: poll job status
    CP-->>Studio: staging graph reference, backend capabilities, review route

No path in P4 can write an active MORK mapping. The worker rejects an activeMappingGraph field outright (projection_lowering.py). Activation is a MORK governance transition, not reachable from this flow.

P5 — MORK Review Decisioning

sequenceDiagram
    actor Steward as Domain Steward
    participant Bench as MORK Review Workbench
    participant CP as Control Plane (MORK API)
    participant PG as PostgreSQL

    Bench->>CP: GET /mork/snapshots/{sectionId}
    CP->>CP: project_evidence(snapshot, role=domain_steward)
    CP-->>Bench: role-safe evidence only
    Steward->>Bench: choose decision (Confirm/Retarget/Reshape/Decline/Teach/Defer)
    Bench->>CP: POST /mork/decisions {snapshotId, snapshotHash, decision, rationale}
    CP->>PG: verify snapshotHash is current
    alt stale
        PG-->>CP: mismatch
        CP-->>Bench: 409 stale snapshot
    else current
        PG-->>CP: recorded
        CP-->>Bench: 200, decision effect (per mork_review.py decision_effect)
    end

This is entirely synchronous. Nothing about recording a human decision requires async processing, only the MORK analysis that produced the snapshot (equivalent to P4’s shape) was asynchronous.

P6 — MORK Queue, Calibration, and Governance

sequenceDiagram
    actor Engineer as Integration Engineer
    actor Owner as Ontology Owner
    participant Bench
    participant CP as Control Plane (Governance API)
    participant PG as PostgreSQL

    Bench->>CP: GET /mork/queue (yield-ordered)
    CP-->>Bench: ordered entries, cross-schema yield annotations
    Engineer->>Bench: attempt bulk confirm
    Bench->>CP: POST /mork/bulk-confirm {packId, profileId, modelId}
    CP->>PG: read calibration_gate for exact triple
    alt gate not passed
        CP-->>Bench: 403, calibration required, current precision shown
    else gate passed
        CP->>PG: apply confirmations
        CP-->>Bench: 200
    end
    Owner->>Bench: propose ontology minting
    Bench->>CP: POST /mork/minting {axiom, affectedApprovals}
    CP->>PG: reopen_approvals, append governance_ledger_entry
    CP-->>Bench: 200, named-axiom reopening recorded

Bulk confirmation is synchronous per request, and the calibration check must complete inside that same request. There is no scenario where a bulk action proceeds before the gate check returns.

P7 — Identity and Authorization

sequenceDiagram
    actor User
    participant Browser
    participant IdP as OIDC Provider (Keycloak)
    participant CP as Control Plane

    User->>Browser: sign in
    Browser->>IdP: authenticate
    IdP-->>Browser: ID token, access token
    Browser->>CP: API call with bearer token
    CP->>CP: verify signature, expiry, issuer
    CP->>CP: construct Principal(subject, tenantId, projectId, roles)
    CP->>CP: GraphAccessPolicy / role check
    alt authorized
        CP-->>Browser: 200 with role-scoped response
    else not authorized
        CP-->>Browser: 403
    end

A Principal is constructed once per request at this boundary and is never accepted as input from a message body or a client-supplied header, per semantic-policy’s existing design.

3. Data Architecture (Summary)

Full detail is in data-architecture.md. The system-of-record answer, repeated here because it is the most-asked question:

No component other than the Control Plane and the worker tier writes any of these stores directly. Browsers never hold a database or broker credential.

4. Component Design

4.1 Component Inventory

4.2 Control Plane Runtime (Decided here)

Gap identified. No HTTP host exists. contracts/openapi/surface-workflow.openapi.json describes a contract with no server, and SurfaceRevisionApi is a transport-neutral adapter with no transport.

Decision. Add one new Maven module, platform/surface-control-plane, containing:

• A minimal HTTP runtime (a single well-chosen library, not a full application framework, consistent with the repository’s stated preference for thin infrastructure over framework weight in repository-delivery-foundation.md).
• A composition root that wires SurfaceRevisionApi, SemanticReleaseCoordinator, MORK review/governance services, GraphAccessPolicy, and an OIDC token verifier together.
• JSON (de)serialization only at the HTTP edge, mapping directly onto the existing typed request/response records, never a second copy of domain validation.
• One process, one deployment unit, per environment. It is not sharded by product (Surface vs MORK) because both share the same identity, policy, and outbox infrastructure, and splitting them would duplicate that wiring for no isolation benefit at this scale.

This is deliberately the smallest correct answer, not a placeholder for a larger framework decision later. It is flagged in §8 as ADR-A44.

4.3 Component Interaction Patterns

4.4 Release Integration Exposure: the Answer to “Who Calls This?”

This section exists because the request that produced this document asked it explicitly. release-integration is a Java library, not a standalone service. It has no network listener of its own and never will, per ADR-A31’s constraint that LATTICE does not become a release engine.

Who calls it. The Control Plane’s Release facade, a thin application service inside surface-control-plane (not yet built, see §4.2), calls SemanticReleaseAssemblyService.assemble(...), then SemanticReleaseCoordinator.publish(...) in-process, in the same JVM, in response to an authenticated HTTP request from the Release Operator (POST /release/candidates/{id}/publish). No message queue sits in front of it, because assembly and packaging are bounded, deterministic operations over already-recorded evidence, not long-running graph computation.

How it is exposed. As an HTTP facade over the library, following the pattern the request describes: “an API acting as a facade in front of something else.” The facade’s job is authentication, request mapping, and translating IllegalArgumentException/IllegalStateException into 4xx responses, exactly as SurfaceRevisionApi already does for the workflow module. No new pattern is introduced, the same one is extended to Release.

Where its evidence goes.

1. ReleaseIntent and ReleaseReceipt are recorded in PostgreSQL by JdbcReleaseLedger, in the tables named in data-architecture.md §2.1.
2. ReleaseProvenanceProjector’s deterministic N-Triples output is written to a dedicated provenance named graph in Fuseki by a new ProvenanceGraphPublisher adapter, called immediately after recordReceipt succeeds. This adapter does not exist yet, it is the one new piece of wiring this decision requires, flagged in data-architecture.md §7.
3. The packaged artifact (OCI layout) is written to a configured directory or, when the optional registry profile is active, pushed by OrasOciRegistryTransport to an OCI-compatible registry. Either way, the receipt’s digest is the durable reference, not the location.

Who inspects it, and what they do with it.

• The Release Operator inspects the release ledger through the Studio Release view specified in ux-design.md §2.4. They decide whether to hand the receipt’s digest to an external release stack for promotion, using whatever mechanism that stack defines (Docker plus CI, Kubernetes GitOps, or a workflow engine, per release-stack-integration.md).
• Auditors query the provenance named graph directly, or read the PostgreSQL ledger, to answer “what evidence backed release X” after the fact, without needing to trust the external release stack’s own records for that answer.
• External release-stack tooling (CI, GitOps controller, or workflow engine) reads only the ReleaseReceipt, specifically its immutable digest and environment binding. It never reads the ReleaseIntent or the provenance graph, because those are LATTICE’s evidence, not deployment instructions. This is the boundary ADR-A31 sets, restated here as a concrete calling contract rather than a principle.

What remains explicitly external. Registry storage lifecycle, signing key custody, deployment mechanics, and retention enforcement remain the responsibility of whatever release stack is configured. release-integration proves LATTICE’s own evidence was correct before handing off, it does not and will not perform the handoff’s downstream steps itself.

4.5 RabbitMQ Topology (Decided here)

Gap identified. platform-outbox’s RabbitMqEventPublisher declares one exchange and one dead-letter exchange per call site, ADR-A37 covers acknowledgement semantics, but no document specifies the full topology across job families.

Decision. One topic exchange and one retry/dead-letter pair per job family, following the pattern already coded in RabbitMqEventPublisher.declareTopology:

Rules that apply uniformly:

• Every primary queue is declared durable, with x-dead-letter-exchange pointing at its family’s retry exchange, matching the existing declareTopology shape.
• Consumers use manual acknowledgement and a bounded prefetch count (starting value 10, tunable per deployment), never auto-ack, per ADR-A37.
• A message that exceeds its retry cap moves to the family’s dead queue and requires an operator replay action, it is never silently dropped.
• Malformed messages (fails to parse as JSON, fails schema validation) are nacked with requeue=false immediately, they do not consume a retry attempt, matching RabbitMqSurfaceWorker’s existing behavior.
• Result publication carries the original correlationId, so the Control Plane can join a result back to the request that caused it without a separate lookup.

4.6 Failure Modes

5. Infrastructure Design

5.1 Deployment Topology

Reference environment (today, Docker Compose):

flowchart TB
  subgraph Host[Developer or pilot host]
    subgraph Compose[docker compose]
      PG[(PostgreSQL)]
      MQ[[RabbitMQ]]
      FK[(Fuseki)]
      OCI[(optional OCI registry)]
      WS[workspace container]
    end
  end
  CPProc[Control Plane process, not yet containerized]
  WorkerProc[Worker process, not yet containerized]
  Browser

  CPProc --> PG
  CPProc --> MQ
  CPProc --> FK
  WorkerProc --> MQ
  WorkerProc --> FK
  WorkerProc --> PG
  CPProc --> OCI
  Browser --> CPProc

The Control Plane and worker processes are not yet containerized or added to Compose, they currently run only as Maven/pytest test targets. Adding them as Compose services is required before the pilot in the platform continuation status can run end to end, and is tracked there, not duplicated here.

Target shape (unchanged topology, hardened operational posture): the same component graph, with PostgreSQL and RabbitMQ given persistent volumes and restart policies, Fuseki given a backup schedule for its dataset directory, and the Control Plane and worker tier each given their own container image with health checks. No additional component is introduced, this is an operational maturity step, not an architecture change, consistent with the single-writer, single-broker posture justified in §7.

5.2 Moving Parts and Communication Matrix

5.3 Observability and Monitoring

Not yet implemented. Sketch only, decided here as the target shape.

5.4 Environments

6. UX Design

Full design is in ux-design.md, which covers the MORK Review Workbench (canonically MORK UXD) and the newly authored Surface Contract Studio design at equivalent depth, including the Release view this document’s §4.4 requires. The cross-cutting principle repeated here because it governs every process map in §2: role perimeters and evidence redaction are enforced server-side, the browser never receives data it must hide from itself.

7. Robustness (Reliability) Design

7.1 Framing: Why CAP Applies Narrowly Here

The CAP theorem describes a tradeoff that only manifests under a network partition between replicas of the same data. This platform, as scoped, runs one authoritative PostgreSQL instance, one authoritative Fuseki dataset, and one RabbitMQ broker per environment. It is not a multi-region, multi-writer, or multi-replica system. That is a deliberate boundary, not an oversight, because the product is a single-tenant-operator “studio” environment, not a globally distributed service.

Given that scope, the request’s aim to achieve C (Consistency) and A (Availability) is satisfied by construction in the absence of a partition, because there is only one partition-capable link in the whole system worth naming: the network path between the Control Plane and its data stores within one environment. The robustness design therefore focuses on what actually threatens this platform: component crashes, message loss, stale concurrent writes, and duplicate delivery, not multi-node network partitions.

7.2 Consistency Mechanisms

7.3 Availability Mechanisms

7.4 Explicit Non-Goals (Deferred, With Reason)

8. Open Decisions and ADR Backlog

Every “Decided here” item above should be ratified as a formal ADR before implementation proceeds past the current pilot slice, per the repository’s own documentation discipline.

9. Traceability Matrix

Ties every capability to the component, data, process, and UX surface that realizes it, for audit and for onboarding.