# poggit-alternative-test/plugin-repository architecture

> Architecture diagram of the GitHub repository poggit-alternative-test/plugin-repository, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/poggit-alternative-test/plugin-repository
- Repository: https://github.com/poggit-alternative-test/plugin-repository

## Overview

#### Purpose and execution model
Axolotl is a GitHub-native trusted distribution pipeline for PocketMine-MP plugins. It turns an untrusted upstream repository commit into a reviewed, preserved source snapshot, an unprivileged PHAR build, and an immutable GitHub Release. The repository is primarily TypeScript CLI tooling and GitHub Actions rather than a web application.

Primary entry points are command-specific CLIs under `src/cli/`, invoked by workflows such as `.github/workflows/validate-submission.yml`, `.github/workflows/materialize-storage.yml`, `.github/workflows/build-trusted.yml`, and `.github/workflows/publish-release.yml`.

#### Registry: declarative source of truth
The registry records plugin identity and version-specific source/release metadata in a filesystem layout rooted at `registry/plugins/`. Parsing, schema validation, semantic validation, and writing are separated in:
- `src/registry/parser.ts`
- `src/registry/validator.ts`
- `src/registry/writer.ts`

JSON Schemas define the external registry/submission contracts in `schemas/plugin.schema.json`, `schemas/version.schema.json`, and `schemas/plugin-submission.schema.json`. Registry changes are expected to arrive through PRs and be validated before review or downstream processing.

#### Submission acquisition and inspection boundary
Submission code treats developer repositories as untrusted input. It acquires candidate metadata/source references, parses plugin manifests, composes results, and emits inspection signals/diagnostics:
- `src/submission/acquisition.ts`
- `src/submission/inspection.ts`
- `src/submission/github.ts`

The `src/cli/inspect-submission.ts` entry point operationalizes this stage. Submission validation is deliberately distinct from approval: automated checks can establish readiness but cannot authorize publication.

#### Human review and approval state
Review is a separate domain that binds approval to a candidate’s exact identity/SHA and checks reviewer authorization and approval preconditions:
- `src/review/candidate-identity.ts`
- `src/review/approval-preconditions.ts`
- `src/review/review-state.ts`

Review records and persistence abstractions live in `src/review/review-record.ts` and `src/review/review-storage.ts`; reviewer policy/configuration is anchored by `config/reviewers.yaml`. The key trust transition is from validated candidate to approved exact source revision, not from successful CI to trusted artifact.

#### Storage materialization
After approval, materialization copies or preserves the reviewed source into the dedicated plugin-storage organization/repository namespace. This domain isolates GitHub authentication and API interaction behind client abstractions:
- `src/materialization/materialization-service.ts`
- `src/materialization/github-client.ts`
- `src/materialization/real-github-client.ts`

Repository naming and transport configuration are explicit in `src/materialization/repository-naming.ts` and `src/materialization/tester-transport-config.ts`. GitHub App authentication is implemented in `src/materialization/github-app-auth.ts`, making GitHub the materialization infrastructure boundary.

#### Trusted build domain
The build stage runs only against materialized source and produces PHAR artifacts, SHA-256/provenance-related diagnostics, without publication credentials. Its orchestration adapters are:
- `src/build/index.ts`
- `src/build/pharynx-runner.ts`
- `src/build/composer-runner.ts`

The isolated builder package under `tools/builder/src/` supplies build-oriented filesystem, manifest validation, and security-scanning capabilities. `src/cli/build-trusted.ts` is the build entry point; `.github/workflows/build-trusted.yml` supplies its CI execution boundary.

#### Privileged publication domain
Publication consumes completed build outputs and publishes releases through a provider abstraction, intentionally without executing plugin code:
- `src/publication/publication-service.ts`
- `src/publication/provider.ts`
- `src/publication/github-provider.ts`

`src/cli/publish.ts` and `.github/workflows/publish-release.yml` drive this privileged stage. `src/publication/fake-provider.ts` supports provider substitution, while the GitHub provider represents the immutable-release external service boundary.

#### End-to-end control flow and trust separation
The lifecycle is: submission/registry PR → validation → human approval of exact SHA → GitHub storage materialization → unprivileged build → privileged GitHub Release publication. CLI layers coordinate each domain, while `src/registry`, `src/submission`, `src/review`, `src/materialization`, `src/build`, and `src/publication` preserve the major security boundaries. GitHub PRs, Actions, GitHub App/API access, storage repositories, and Releases are the material infrastructure; no custom persistent backend is indicated.

Main entry points: [`src/build/index.ts`](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/build/index.ts) (Trusted build), [`src/registry/validator.ts`](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/registry/validator.ts) (Registry parser & validator), [`src/submission/inspection.ts`](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/submission/inspection.ts) (Submission inspection), [`src/review/review-state.ts`](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/review/review-state.ts) (Approval state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Intake & Review"]
  node_registry["Plugin registry<br/>declarative registry"]
  node_schemas["Registry schemas<br/>JSON schemas<br/>[plugin.schema.json]"]
  node_registry_logic["Registry parser &amp; validator<br/>registry domain<br/>[validator.ts]"]
  node_submission_inspection["Submission inspection<br/>untrusted-input domain<br/>[inspection.ts]"]
  node_inspect_cli{{"Inspect submission CLI<br/>CLI entry point"}}
  node_review_state["Approval state<br/>review domain<br/>[review-state.ts]"]
  node_review_policy["Reviewer policy<br/>review configuration<br/>[reviewers.yaml]"]
end

subgraph group_supply["Trusted Supply Chain"]
  node_materialization["Materialization service<br/>storage domain"]
  node_trusted_build["Trusted build<br/>build domain<br/>[index.ts]"]
  node_builder_tools["Isolated builder<br/>builder package"]
  node_build_cli{{"Build trusted CLI<br/>CLI entry point<br/>[build-trusted.ts]"}}
  node_publication["Publication service<br/>privileged publication domain"]
  node_publish_cli{{"Publish CLI<br/>CLI entry point<br/>[publish.ts]"}}
end

subgraph group_github["GitHub Infrastructure"]
  node_validation_workflow["Validate submission<br/>GitHub Actions workflow"]
  node_pull_request["Registry PR<br/>GitHub PR"]
  node_materialize_workflow["Materialize storage<br/>GitHub Actions workflow"]
  node_github_app{{"GitHub App &amp; API<br/>infrastructure boundary<br/>[github-app-auth.ts]"}}
  node_storage_repos[("Plugin storage repos<br/>preserved source")]
  node_build_workflow["Build trusted<br/>GitHub Actions workflow<br/>[build-trusted.yml]"]
  node_publish_workflow["Publish release<br/>GitHub Actions workflow"]
  node_github_releases[("Immutable GitHub Releases<br/>external release service<br/>[github-provider.ts]")]
end

node_pull_request -->|"changes"| node_registry
node_schemas -->|"contracts"| node_registry_logic
node_registry -->|"read and validate"| node_registry_logic
node_validation_workflow -->|"runs"| node_inspect_cli
node_inspect_cli -->|"inspects"| node_submission_inspection
node_registry_logic -->|"metadata context"| node_submission_inspection
node_submission_inspection -->|"validated candidate"| node_review_state
node_review_policy -->|"authorizes reviewers"| node_review_state
node_review_state -->|"approved exact SHA"| node_materialize_workflow
node_materialize_workflow -->|"runs"| node_materialization
node_materialization -->|"uses authenticated API"| node_github_app
node_github_app -->|"preserves source"| node_storage_repos
node_storage_repos -->|"materialized source"| node_build_workflow
node_build_workflow -->|"runs"| node_build_cli
node_build_cli -->|"orchestrates"| node_trusted_build
node_trusted_build -->|"uses isolated capabilities"| node_builder_tools
node_trusted_build -->|"completed artifacts"| node_publish_workflow
node_publish_workflow -->|"runs"| node_publish_cli
node_publish_cli -->|"orchestrates"| node_publication
node_publication -->|"publishes immutable release"| node_github_releases

click node_schemas "https://github.com/poggit-alternative-test/plugin-repository/blob/main/schemas/plugin.schema.json"
click node_registry_logic "https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/registry/validator.ts"
click node_submission_inspection "https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/submission/inspection.ts"
click node_inspect_cli "https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/cli/inspect-submission.ts"
click node_validation_workflow "https://github.com/poggit-alternative-test/plugin-repository/blob/main/.github/workflows/validate-submission.yml"
click node_review_state "https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/review/review-state.ts"
click node_review_policy "https://github.com/poggit-alternative-test/plugin-repository/blob/main/config/reviewers.yaml"
click node_materialization "https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/materialization/materialization-service.ts"
click node_materialize_workflow "https://github.com/poggit-alternative-test/plugin-repository/blob/main/.github/workflows/materialize-storage.yml"
click node_github_app "https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/materialization/github-app-auth.ts"
click node_trusted_build "https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/build/index.ts"
click node_build_cli "https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/cli/build-trusted.ts"
click node_build_workflow "https://github.com/poggit-alternative-test/plugin-repository/blob/main/.github/workflows/build-trusted.yml"
click node_publication "https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/publication/publication-service.ts"
click node_publish_cli "https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/cli/publish.ts"
click node_publish_workflow "https://github.com/poggit-alternative-test/plugin-repository/blob/main/.github/workflows/publish-release.yml"
click node_github_releases "https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/publication/github-provider.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_registry,node_schemas,node_registry_logic,node_submission_inspection,node_inspect_cli,node_review_state,node_review_policy toneBlue
class node_materialization,node_trusted_build,node_builder_tools,node_build_cli,node_publication,node_publish_cli toneAmber
class node_validation_workflow,node_pull_request,node_materialize_workflow,node_github_app,node_storage_repos,node_build_workflow,node_publish_workflow,node_github_releases toneMint
```

## Components

### Intake & Review

Untrusted submission validation and human approval.

- **Plugin registry**: declarative registry · Versioned plugin source and release metadata.
- [Registry schemas](https://github.com/poggit-alternative-test/plugin-repository/blob/main/schemas/plugin.schema.json): JSON schemas · External registry and submission contracts. · `schemas/plugin.schema.json`
- [Registry parser & validator](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/registry/validator.ts): registry domain · Parses, semantically validates, and writes registry records. · `src/registry/validator.ts`
- [Submission inspection](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/submission/inspection.ts): untrusted-input domain · Acquires candidate references, manifests, and diagnostics. · `src/submission/inspection.ts`
- [Inspect submission CLI](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/cli/inspect-submission.ts): CLI entry point · `src/cli/inspect-submission.ts`
- [Approval state](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/review/review-state.ts): review domain · Binds approval to the exact candidate identity and SHA. · `src/review/review-state.ts`
- [Reviewer policy](https://github.com/poggit-alternative-test/plugin-repository/blob/main/config/reviewers.yaml): review configuration · `config/reviewers.yaml`

### Trusted Supply Chain

Materialize, build, and publish after approval.

- [Materialization service](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/materialization/materialization-service.ts): storage domain · Preserves approved source in dedicated storage repositories. · `src/materialization/materialization-service.ts`
- [Trusted build](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/build/index.ts): build domain · Builds PHARs and emits SHA-256 and provenance diagnostics without publication credentials. · `src/build/index.ts`
- **Isolated builder**: builder package · Filesystem, manifest validation, and security-scanning capabilities.
- [Build trusted CLI](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/cli/build-trusted.ts): CLI entry point · `src/cli/build-trusted.ts`
- [Publication service](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/publication/publication-service.ts): privileged publication domain · Publishes completed outputs without executing plugin code. · `src/publication/publication-service.ts`
- [Publish CLI](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/cli/publish.ts): CLI entry point · `src/cli/publish.ts`

### GitHub Infrastructure

PR, Actions, API, storage, and release boundaries.

- [Validate submission](https://github.com/poggit-alternative-test/plugin-repository/blob/main/.github/workflows/validate-submission.yml): GitHub Actions workflow · `.github/workflows/validate-submission.yml`
- **Registry PR**: GitHub PR · Submission and registry changes enter through reviewable PRs.
- [Materialize storage](https://github.com/poggit-alternative-test/plugin-repository/blob/main/.github/workflows/materialize-storage.yml): GitHub Actions workflow · `.github/workflows/materialize-storage.yml`
- [GitHub App & API](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/materialization/github-app-auth.ts): infrastructure boundary · Authenticated repository materialization access. · `src/materialization/github-app-auth.ts`
- **Plugin storage repos**: preserved source · Dedicated namespace containing reviewed source snapshots.
- [Build trusted](https://github.com/poggit-alternative-test/plugin-repository/blob/main/.github/workflows/build-trusted.yml): GitHub Actions workflow · `.github/workflows/build-trusted.yml`
- [Publish release](https://github.com/poggit-alternative-test/plugin-repository/blob/main/.github/workflows/publish-release.yml): GitHub Actions workflow · `.github/workflows/publish-release.yml`
- [Immutable GitHub Releases](https://github.com/poggit-alternative-test/plugin-repository/blob/main/src/publication/github-provider.ts): external release service · `src/publication/github-provider.ts`

## Connections

- Registry PR → Plugin registry: changes
- Registry schemas → Registry parser & validator: contracts
- Plugin registry → Registry parser & validator: read and validate
- Validate submission → Inspect submission CLI: runs
- Inspect submission CLI → Submission inspection: inspects
- Registry parser & validator → Submission inspection: metadata context
- Submission inspection → Approval state: validated candidate
- Reviewer policy → Approval state: authorizes reviewers
- Approval state → Materialize storage: approved exact SHA
- Materialize storage → Materialization service: runs
- Materialization service → GitHub App & API: uses authenticated API
- GitHub App & API → Plugin storage repos: preserves source
- Plugin storage repos → Build trusted: materialized source
- Build trusted → Build trusted CLI: runs
- Build trusted CLI → Trusted build: orchestrates
- Trusted build → Isolated builder: uses isolated capabilities
- Trusted build → Publish release: completed artifacts
- Publish release → Publish CLI: runs
- Publish CLI → Publication service: orchestrates
- Publication service → Immutable GitHub Releases: publishes immutable release