Engineering & Platform
The running system, on the graph that traces back to the need
An architecture diagram is accurate the day it is drawn and wrong a sprint later, because the system moves and the diagram does not. UPG types the system around the service: the bounded context and the ADR that shaped it, the API contract it exposes, the schema it persists in, the deployment it ships as, the SLOs that watch it, and the threats it faces all hang off one live node. The structure updates as the system does, and the feature a service powers traces all the way back to the user need that justifies it.
“Organizations which design systems are constrained to produce designs which are copies of the communication structures of these organizations.”
The bounded context is the unit of architecture
A bounded contextbounded_contextA DDD bounded context defining a service boundary is the unit of architecture. It deploys a serviceserviceA deployable service or microservice, is modelled as an aggregateaggregateA DDD aggregate root, emits a domain eventdomain_eventAn event published when something happens in the domain, and publishes an api contractapi_contractAn API contract or specification. The decisiondecisionA recorded decision with context, rationale, and consequences that shaped it (the ADR) is captured as a node connected to what it shaped.
The reasoning outlasts the people who made it. The question of why the reporting context is event-sourced resolves to the decision node and everything that followed from it, available long after the author has moved on.
a boundary in the systembounded_contextA DDD bounded context defining a service boundaryserviceA deployable service or microservicedecisionA recorded decision with context, rationale, and consequencesaggregateA DDD aggregate rootdomain_eventAn event published when something happens in the domainapi_contractAn API contract or specificationA bounded context deploys services, is modelled as aggregates, emits domain events, and publishes its contract. The decision that shaped it is a node in the graph, connected by one edge to the bounded context it governs. The ADR is held as an entity rather than a separate wiki page.
The service is the join across the whole stack
A serviceserviceA deployable service or microservice exposes an api contractapi_contractAn API contract or specification, persists in a database schemadatabase_schemaA database schema definition, deploys as a deploymentdeploymentA deployment event, and powers a featurefeatureA product capability or feature. Each is a typed edge, so the service node is the join between architecture, delivery, and operations.
The feature a service powers is the same feature the roadmap tracks and the user need justifies, and the technical debt itemtechnical_debt_itemA known piece of technical debt it carries is a node a planner can read alongside the rest of the work. The question of what breaks if this service changes resolves to the nodes on the other end of its edges.
serviceA deployable service or microserviceapi_contractAn API contract or specificationdatabase_schemaA database schema definitiondeploymentA deployment eventfeatureA product capability or featuretechnical_debt_itemA known piece of technical debtA service is the engineering anchor: it exposes an API contract, persists in a schema, deploys as a deployment, and powers a feature. Architecture stops being a diagram that rots in a wiki, because the same service node the product feature points to is the one the deployment and the schema hang off. The feature it powers traces all the way back to the user need.
The blast radius of a contract change is a traversal
An api contractapi_contractAn API contract or specification contains the api endpointapi_endpointA specific API endpoint nodes it ships and records the decisiondecisionA recorded decision with context, rationale, and consequences behind their shape, and each endpoint serves a featurefeatureA product capability or feature. The contract is structure in the graph rather than a comment in a handler.
A change to the contract resolves to every feature riding on it before the change ships, while it is still a review and not yet a consumer’s production incident. The most dangerous change in engineering becomes a query that runs ahead of the deploy.
api_contractAn API contract or specificationapi_endpointA specific API endpointapi_endpointA specific API endpointdecisionA recorded decision with context, rationale, and consequencesfeatureA product capability or featureAn API contract contains the endpoints it ships and records the decision behind their shape, and each endpoint serves a feature. Because the contract is a node, the features affected by a breaking change are a query over the graph, resolved before the change ships.
The path to production, typed end to end
A serviceserviceA deployable service or microservice produces a build artifactbuild_artifactA build output (binary, container image), toggles a feature flagfeature_flagA feature toggle for controlled rollout, and is deployed as a deploymentdeploymentA deployment event. The deploy is wired to its blast radius: the deployment triggers the incidentincidentA production incident when a release goes wrong.
The question “what changed right before this broke?” resolves to the deploy that triggered the incident. Shipping and the consequences of shipping live in the same graph, connected by the edge between them.
serviceA deployable service or microservicebuild_artifactA build output (binary, container image)feature_flagA feature toggle for controlled rolloutdeploymentA deployment eventdeploymentA deployment eventincidentA production incidentA service produces a build artifact, toggles a feature flag, and is deployed as a deployment, and that deployment triggers the incident when a release goes wrong. The change that preceded an incident is a traversal back along the deployment edge.
Reliability targets as typed nodes
A service level objectiveservice_level_objectiveA service level objective (SLO) is measured by a service level indicatorservice_level_indicatorA service level indicator (SLI), tracks the metricmetricA unified metric that measures progress, health, or behaviour across the product behind it, and budgets the error budgeterror_budgetAn error budget for a service it can afford. When an incidentincidentA production incident breaches the objective, the breach is linked to the objective it broke.
The state of the error budget is a number on the graph, the same one every team reads. The SLO is a live node connected to the indicator that measures it and to the incidents that spend it.
service_level_objectiveA service level objective (SLO)service_level_indicatorA service level indicator (SLI)metricA unified metric that measures progress, health, or behaviour across the producterror_budgetAn error budget for a serviceincidentA production incidentservice_level_objectiveA service level objective (SLO)An SLO is measured by an indicator, tracks the metric behind it, and budgets the error it can afford, and an incident that breaches it is linked to the objective it broke. The remaining error budget is a value on the graph, read the same way by every team.
Threats and controls, connected to the system they cover
A threat modelthreat_modelA threat model for the system identifies a threatthreatA specific security threat and surfaces a vulnerabilityvulnerabilityA known vulnerability, and a security controlsecurity_controlA security control or mitigation mitigates the threat and protects the serviceserviceA deployable service or microservice it guards.
The question “which threats to the reporting service are still unmitigated?” resolves to a traversal across these edges. Security is structure connected to the system it defends, so a new service with no control attached stands out the moment it ships.
threat_modelA threat model for the systemthreatA specific security threatvulnerabilityA known vulnerabilitysecurity_controlA security control or mitigationserviceA deployable service or microserviceA threat model identifies threats and surfaces vulnerabilities, and a security control mitigates the threat and protects the service it guards. The threats to the reporting service that remain unmitigated are a query over these edges, current as of the last assessment recorded on them.
Engineering sits between the product it builds and the operations that keep it up. Follow a thread in either direction:
Architecture, services, APIs, data, deploy, monitor, and security, with every property and edge.
The feature a service powers and the task that builds it.
The incidents, SLOs, and root causes a service connects to once it is running.