Component Model
Component Model
Section titled “Component Model”A sigMAX component is an autonomous deployable unit executed inside a container by a standardized runtime.
The component model defines what a component must expose so it can be generated, inspected, validated, and operated without guessing its internal implementation.
Component Responsibilities
Section titled “Component Responsibilities”A component should make its operational and application boundary explicit.
| Area | Responsibility |
|---|---|
| API surface | Expose the routes, methods, schemas, and generated OpenAPI description expected by the contract. |
| Runtime integration | Run through the standardized sigMAX runtime and only use allowed capabilities. |
| Discovery | Publish metadata that lets tools inspect what was generated. |
| Health | Provide a predictable health endpoint for local and orchestrated execution. |
| Documentation | Produce human-readable documentation for review and audit. |
| Evidence | Record generated files, endpoints, images, metadata, and validation output in the component agreement. |
Standard Surfaces
Section titled “Standard Surfaces”The exact surface can vary by component type, but a sigMAX component should keep the common inspection points stable.
| Surface | Purpose |
|---|---|
.well-known | Discovery metadata for tools and local inspection. |
openapi.yaml | API contract generated for exposed routes. |
healthz | Operational health check. |
metrics | Runtime or business metrics when the edition and component enable them. |
docs | Human-readable component documentation. |
| Component Agreement | Effective state used for validation and drift detection. |
Model Flow
Section titled “Model Flow”The component model sits between the application topology and the binary/runtime boundary.
Contract And Agreement
Section titled “Contract And Agreement”The Component Contract describes the expected component surface before generation.
It can define:
- component identity and responsibility;
- exposed routes and route visibility;
- expected OpenAPI output;
- required discovery and documentation files;
- health endpoint expectations;
- allowed runtime primitives and capabilities;
- referenced binary contracts;
- generated artifacts that must be recorded.
The Component Agreement records what was actually produced.
It can include:
- generated route list and OpenAPI file path;
- discovered endpoints and metadata;
- generated docs and file hashes;
- container image reference;
- referenced WASM artifacts and binary agreements;
- validation status and drift evidence.
Relation To The Runtime
Section titled “Relation To The Runtime”The runtime gives components a consistent execution boundary.
A component should not directly assume unrestricted host access. It should use the runtime capabilities allowed by its contract. This keeps the generated system inspectable and helps detect when a component accidentally exposes a route, imports a forbidden primitive, or depends on a capability that was not declared.
Drift Examples
Section titled “Drift Examples”Component drift can appear when:
- an endpoint exists in the generated OpenAPI file but not in the contract;
- a documented route is missing from the generated component;
- the component imports a binary that was not declared;
- health or discovery metadata is missing;
- a component exposes something publicly that was expected to remain internal;
- generated documentation no longer matches the effective surface.
Design Rules
Section titled “Design Rules”A good component model should be:
- autonomous enough to deploy and inspect locally;
- explicit about its API and runtime boundary;
- linked to binary contracts when executable WASM is involved;
- predictable in health, discovery, and documentation surfaces;
- strict enough to support drift detection;
- simple enough for Studio and local tooling to inspect.