eclipse-score/communication/score-architecture

S-CORE Architecture Skill

Software architectural design for a Safety Element out of Context (SEooC) using the rules_score Bazel rules. Architecture is expressed as PlantUML diagrams and as Bazel targets; rules_score automatically verifies that the two stay consistent and assembles them into Sphinx documentation with a traceability report.

The PlantUML `static` diagram is the design; the Bazel model is a mechanical transcription of it. Always design first (collaboratively, in PlantUML), agree the decomposition with the user, then write the Bazel targets. See Workflow below.

Source of truth: the rule macros under bazel/rules/rules_score/private/

(architectural_design.bzl, unit.bzl, unit_design.bzl, component.bzl,

dependable_element.bzl), the validator specifications in

`validation/core/docs/specifications/` (what is

checked + which PlantUML notation is valid), and the standalone examples in

`bazel/rules/rules_score/examples/`

(seooc/ and minimal/). When source and documentation disagree, the source wins. Every

code block in this skill is quoted verbatim from those examples/specs.

When to use

• Writing PlantUML architecture diagrams (static, dynamic, public_api, internal_api)
• Structuring the dependable_element → component → unit hierarchy in Bazel
• Wiring architectural_design, unit, unit_design, component, dependable_element
• Understanding the architecture consistency, certified-scope, and integrity-level checks

Not for

• Requirement records and traceability → score-requirements
• FMEA / FailureMode / FTA safety analysis → score-safety-analysis
• Test annotation and coverage → score-testing
• End-to-end SEooC assembly / choosing which skill to use → rules-score

Workflow: design first in PlantUML, then model in Bazel

Architecture work in rules_score has two phases, in strict order. Do not merge them, and do not start with the Bazel targets.

Step 1 — Design the targeted architecture (PlantUML static) — collaborative

The static PlantUML diagram is the design artifact and the first thing you produce. It captures the intended decomposition: which components and units exist, how they nest, and which interfaces connect them. This is a design decision, not a transcription — use the criteria in Determining Components & Units below to shape it.

Collaborate with the user here — do NOT silently guess a decomposition. Unit/component boundaries are rarely unambiguous, so when uncertain:

• Propose one or two concrete decomposition options, each with the trade-offs (cohesion,

interface count, requirement allocation, failure containment), and ask the user to choose.

• Ask clarifying questions about feature boundaries, ownership, which behaviour is public vs

internal, and expected unit interactions.

• Iterate on the static diagram (and, if useful, public_api / internal_api / dynamic)

until the user explicitly agrees. The agreed diagram is the targeted architecture.

Step 1 is not done until the user has signed off on the decomposition. Treat an unclear

component/unit split as a blocker to resolve with the user, not a detail to invent.

Step 2 — Model the agreed architecture in Bazel — mechanical

Only after the targeted architecture is agreed, translate it 1:1 into Bazel targets. This step is mechanical: every <<SEooC>> / <<component>> / <<unit>> in the diagram becomes a dependable_element / component / unit target with the same name and the same nesting. The bazel_component validator enforces that the Bazel model matches the diagram exactly, so there are no design decisions left here — only faithful transcription.

Never write the Bazel targets first and reverse-engineer a diagram to match. The diagram is the

design; the Bazel model follows it.

Declared vs. Implemented Architecture

• Declared — the PlantUML diagrams passed to architectural_design (static, dynamic,

public_api, internal_api). What the architecture is supposed to look like.

• Implemented — the actual Bazel targets: unit(implementation = [...]) wraps real source,

component(components = [...]) groups units, dependable_element(components = [...]) assembles the SEooC. What the architecture actually is.

Because both views are authored independently they can drift. rules_score runs an architecture consistency check at build time: every component/unit in dependable_element.components must appear, under the same name, in the static PlantUML diagram — and vice versa. A mismatch fails the build.

Hierarchy

dependable_element   (SEooC — complete Safety Element out of Context)
└── component        (groups units; owns component requirements + integration tests)
    ├── unit         (smallest independently verifiable element: implementation + unit tests)
    └── component    (components can nest for deeper hierarchies)
        └── unit

Two rules:

• A unit must always be wrapped in a component — it cannot sit directly under

dependable_element.

• A component may nest: it can contain other components as well as units, to arbitrary depth.

Determining Components & Units (authoring guidance)

The rules only check that the declared and implemented structure match — not that the decomposition is good. Deciding what becomes a component vs a unit is a design activity governed by the S-CORE Architecture Design process area; the authoritative distillation lives in `docs/user_guide/architectural_design.rst` (Determining Components and Units). Decompose top-down from the SEooC's public API and requirements until every leaf is a testable unit.

A `unit` is the smallest independently verifiable element. Model as a unit when ALL hold:

• Single responsibility — statable in one sentence with no "and".
• Independently unit-testable through a narrow interface, without the rest of the SEooC.
• Cohesive implementation — its source files change together and share data.
• One owner; backed by a unit_design validated against the code.

Split a unit as soon as its class diagram grows unrelated class clusters or its

tests split into groups that never share fixtures.

A `component` groups collaborating units that realise one feature or provide one internal interface. Introduce a component when:

• Several units together deliver one feature / one internal API.
• There is behaviour that only emerges from unit interaction → owns **component

integration tests and CompReq** records.

• You need a stable boundary to allocate requirements and reason about in safety analysis.

Boundary heuristics (high cohesion / low coupling applied to the element levels):

Public vs internal interface: an interface is public API only when it is part of the SEooC's contract with its environment (bound from <<SEooC>>, feeds FailureMode.interface). Keep it minimal — every public method is an obligation and a safety-analysis entry point. Everything else is internal API, modeled inside the owning element's namespace. Promote internal → public only when an external requirement forces it.

Anti-patterns: folder-driven decomposition (component per directory), god unit (unrelated responsibilities accreted into one unit), anaemic component (only forwards calls, owns no tests/requirements), leaky public API (exposed for convenience, drags in extra failure modes and AoUs).

Static Architecture (PlantUML) — Step 1 (design)

This is the design step: produce and agree this diagram with the user before any Bazel targets exist (see Workflow). Write a class/component diagram that names every component and unit of the intended decomposition. The validator identifies elements by their stereotype, not by the PlantUML keyword — both package and component keywords are accepted at each level.

@startuml static_design
 
package safety_software_seooc_example <<SEooC>> {
    component component_example <<component>> {
        component unit_1 <<unit>>
        component unit_2 <<unit>>
        component sub_component_example <<component>>
 
        interface InternalInterface
        unit_1 -l-( InternalInterface
        unit_2 -r- InternalInterface
    }
}
 
interface SampleLibraryAPI
 
safety_software_seooc_example -d- SampleLibraryAPI
 
@enduml

(Verbatim from [`examples/seooc/design/static_design.puml`](../../../bazel/rules/rules_score/examples/seooc/design/static_design.puml). The three `<<component>>`/`<<unit>>` names — `component_example`, `unit_1`, `unit_2`, `sub_component_example` — are exactly the Bazel target names, and `safety_software_seooc_example` matches the `dependable_element` name.)

Interfaces & ports

Any component-type element (<<SEooC>> or <<component>>) can bind an interface with lollipop syntax — -( for a required (incoming) binding and -, --, or --() for a provided (outgoing) one. The bazel_component validator does not check interface bindings themselves, but the API and sequence validators do (see below).

When you need an explicitly named, standalone binding point (e.g. to distinguish multiple provided interfaces), declare a portin / portout inside the <<SEooC>> or <<component>> element (from the bazel_component validator spec):

package MySeooc <<SEooC>> {
    portin  p_in   ' required interface port
    portout p_out  ' provided interface port
}
 
interface IRequired
interface IProvided
 
p_in  -( IRequired : requires
p_out - IProvided : provides

• portin / portout must be declared inside the <<SEooC>> or <<component>> element.
• A plain package without a stereotype cannot carry interface bindings.
• Elements with other stereotypes (actor, database, …) are not valid on the left of a binding.

Dynamic, Public API, Internal API

Every diagram kind is checked by one or more validators (see Active validations below) — none of them is "documentation only". static is checked against the Bazel structure; the others are cross-checked against each other and against the implementation.