Architecture¶
This document describes the released Protocolith system as a set of actors and actions. It is intentionally limited to the public repository and its documented release/validation paths.
Actors and subsystems¶
| Actor / subsystem | Can influence | Actions |
|---|---|---|
| Human contributor | Source tree and pull requests | Creates commits, opens PRs, adds tests/docs/cards and responds to review |
| Maintainer | Protected repository, releases and security handling | Reviews/merges PRs, manages repository configuration, tags/releases, handles vulnerabilities |
| GitHub repository | Source and protected integration state | Stores source, issues, PRs, releases, rulesets and workflow definitions |
| GitHub Actions | Build/test/release outputs | Runs checkout, dependency installation, validation, tests, package build, attestation and publication workflows |
| Python package tooling | Build artifacts | Builds the Python sdist and wheel from repository state |
| Protocolith CLI | Evidence files supplied by an operator | Validates cards, registry data and repository-level evidence according to implemented protocols |
| Evidence registry | Public metadata index | Maps published evidence identifiers to validated card JSON and metadata |
| External source / artifact | Input to an evidence run | Supplies public source material or an artifact whose boundary is recorded by a card |
| PyPI Trusted Publishing | Published Python packages | Receives release artifacts from the protected GitHub Actions workflow using OIDC |
Main actions and data flow¶
Evidence validation¶
- An operator supplies a Protocolith card, registry entry or supported evidence input.
- The Protocolith CLI reads the declared protocol, source boundary, hashes and result fields.
- Validators check the applicable schema, protocol constraints and cross-file relationships.
- The CLI reports a validation result; it does not provide certification or make a general quality/safety determination.
- Maintainers may review the resulting change through the normal pull-request process.
Repository contribution¶
- A contributor creates commits and signs each commit under the DCO.
- A pull request triggers automated checks, including DCO, dependency review and tests.
- Required checks and repository review rules govern acceptance into main.
- A maintainer merges the pull request.
Release¶
- A maintainer publishes a GitHub Release.
- The release workflow checks out the tagged repository state and builds the Python distribution artifacts.
- The workflow generates SHA-256 hashes for the build artifacts.
- GitHub artifact attestations are generated for the artifacts and release manifest.
- The release assets and hash manifest are uploaded to the GitHub Release.
- PyPI publication uses OIDC Trusted Publishing rather than a long-lived PyPI token.
Trust boundaries¶
- Public source and issue/PR content are untrusted contributor input.
- Evidence source material is treated according to the source boundary declared by the evidence card; raw/private payloads are outside the public repository boundary.
- GitHub Actions workflows are privileged automation and therefore use explicit job permissions.
- Release publication and repository administration are maintainer-controlled operations.
- PyPI is an external package distribution service; Protocolith does not control downstream installations or environments.
Update rule¶
Update this document when a new subsystem, external service, privileged workflow action, public interface or material data flow is introduced, or when a breaking change alters the actors/actions described above.