Code Architecture

This record answers one question: how is the implementation divided, and which direction may dependencies flow? It does not define note kinds, document the build lifecycle, or enumerate the repository tree; those belong to content-model, build-and-validation, and repository-layout.

Component stack

                    site (Astro)
                         │
                 build-cli (authoring)
                 │        │          │
                 ▼        ▼          ▼
          note-schema  gxwf-pi-harness ──▶ foundry CLI
                 │        │                  │
                 ▼        ▼                  ▼
  shared substrate        Pi          summarize-nextflow

shared substrate = cast, kind-schema, kind-manifest, tag-registry,
reference-contract, wiki-links, content-reader, and license-policy packages

The arrows point toward dependencies. The site and build CLI are composition layers: they join instance contracts, shared substrate packages, and runtime packages into user-facing behavior. Lower layers do not import either application.

cast is the load-bearing substrate package. It implements casting itself — reference resolution, placement, the skill renderer, the orphan sweep, the provenance record — and this Foundry’s own knowledge reaches it through CastHooks. Both build-cli and note-schema depend on it: the first because it casts, the second because the cast: half of a reference kind is parsed there. The site therefore reaches it transitively, which costs nothing at build time and is worth knowing when reading the graph above.

Components and ownership

@galaxy-foundry/gxwf-foundry-note-schema

The instance’s content-contract package. It owns:

• the base frontmatter envelope;
• one definition directory per note kind;
• collection paths and note shapes;
• instance composition of tag, reference, and license registries;
• the generated kind manifest contract.

It builds on the shared @galaxy-foundry/* substrate packages. The package exports the same assembled schemas and collection table to both the validator and the site, preventing a second frontmatter encoding.

It also owns the strict loader and shared types for the repository-level runtime-artifact registry. The validator, caster, assembler, and site all consume that one interpretation of runtime_artifacts.yml.

@galaxy-foundry/build-cli

The authoring and build application exposed as foundry-build. It owns repository-wide operations:

• static content validation and cross-note checks;
• dashboard, index, README-stat, and kind-manifest generation;
• what this Foundry contributes to a cast, and cast verification;
• Pipeline assembly;
• repository-wide registries and file walking, including runtime-artifact collision checks, producer validation, and inheritance.

Root files under scripts/ are thin compatibility wrappers, sync commands, or one-time maintenance utilities. New reusable authoring behavior belongs in build-cli, not in another root script.

@galaxy-foundry/gxwf-foundry

The runtime-facing CLI and schema bundle. It owns validation commands for structured Mold artifacts and exports schemas whose producer is not another in-repository package. It is distinct from foundry-build: the build CLI operates on the Foundry repository; the runtime CLI travels with or supports cast workflows.

@galaxy-foundry/summarize-nextflow

A domain runtime package that summarizes Nextflow source and owns the schemas produced by that operation. Producer-owned schemas remain with their producer; @galaxy-foundry/gxwf-foundry holds the orphan schemas with no independent in-repository producer.

@galaxy-foundry/gxwf-pi-harness

The optional evaluation-runtime adapter. It owns the single-skill Pi RPC worker, normalized run records, declared-input staging, artifact verification, the foundry_subagent Pi extension, and the public pi-test-auth adapter for isolated OpenAI/Codex OAuth credentials. It depends on the runtime-facing foundry CLI and resolves that package directly for independent artifact validation rather than relying on an ambient executable. foundry-build test-skill and test-pipeline supply the repository-facing commands, but trace-mode callers and the extension use this package’s one runner. Pipeline phase selection remains in build-cli; the harness accepts one published skill bundle and does not read authored Molds, select Pipeline phases, or grade qualitative properties. OAuth is available only to explicitly local diagnostic workers, while whole-process container workers continue to receive only allowlisted API-key environment variables.

@galaxy-foundry/nfcore-tool-lab

A standalone domain runtime CLI and typed API that prepares an already converted nf-core tool for galaxyproject/tools-iwc-lab. Its offline prepare operation owns mechanical experimental naming, lab Tool Shed metadata, documentation, explicit asset copying, macro-import completeness checks, and a separate preparation record with input/output content hashes. It preserves conversion provenance and all XML bytes outside the tool’s root identity values. The opt-in stage controller and separate /stage API reuse preparation, run final-payload Planemo lint/Shed metadata/Galaxy tests, verify local converter-bundle/run consistency and destination-name collisions, and require hash-bound human license/coverage attestations. Staging emits a separate validation record and draft PR proposal; it depends on the published Planemo test-report schema but not repository authoring code or the Pi/model runtime. Local execution is not a security boundary. Model conversion sequencing, upstream authentication, destination CI confirmation, credential-bearing GitHub writes, and Tool Shed deployment remain later harness responsibilities.

Metadata packages

@galaxy-foundry/planemo-cli-meta and @galaxy-foundry/planemo-test-report-schema are generated, version-pinned views of Planemo interfaces. Normal validation consumes the checked-in artifacts without requiring Planemo to be installed.

Astro site

site/ is the human reading application. It imports the note schemas and collection table rather than reconstructing them. Its local code owns presentation concerns: note registries, backlinks, remark transforms, specialized bodies, routes, and styling. It may read cast metadata for presentation, but it does not produce casts.

Shared implementation seams

• Kinds: @galaxy-foundry/kind-schema defines the generic kind contract; this instance supplies concrete kinds and context through note-schema.
• Kind manifests: @galaxy-foundry/kind-manifest derives and reads the portable description of those concrete kinds.
• Tags: @galaxy-foundry/tag-registry owns the registry format and how tags browse — grouping by declaring facet, facet labels; meta_tags.yml owns this instance’s vocabulary, and the site owns only what counts as a tagged note.
• References: @galaxy-foundry/reference-contract owns shared reference behavior; reference_contract.yml owns instance reference kinds and permitted combinations.
• Artifacts: Mold output_artifacts[] and root runtime_artifacts.yml contribute to one producer graph. note-schema owns the runtime-registry format, loader, and shared types; build-cli owns collision checks, validator integration, harness behavior, and cast-provenance projection; the site renders both producer kinds from the same registry.
• Wiki links: @galaxy-foundry/wiki-links owns parsing, slugging, resolution, and tree traversal; the site and validator supply the instance link map.
• Reading the content tree: @galaxy-foundry/content-reader owns the walk, the frontmatter read, and the address-precedence rule that turns a routed note into the slugs reaching it. build-cli supplies the collection table and this instance’s aliases, and the validator and the caster project their maps from one reader so a link one calls good cannot fail in the other. The site still builds its own map from astro:content, which is already loaded there.
• Licenses: @galaxy-foundry/license-policy answers general redistribution questions; instance validation owns coherence rules for its notes.

Composition happens at narrow adapters such as the schema context, registries, and site link-map builder. Application code imports the shared package directly when no instance-specific composition is required.

External tool boundary

gxwf, Planemo, and Pi are not implementation layers in this repository. Molds describe when to use gxwf and Planemo, CLI notes document their exact commands, and generated skills invoke them. The optional gxwf-pi-harness adapter invokes pinned Pi as an evaluation worker. Repository validation does not require any of these tools to run; their execution remains a design-time, cast-runtime, or opt-in evaluation concern.

Cross-component contracts

1. The note-schema package is the only frontmatter authority.
2. The collection table drives validator walking, Astro loading, wiki-link reachability, and kind manifests.
3. The build CLI may depend on runtime/schema packages; runtime packages do not depend on repository authoring code.
4. The site consumes schemas and content but never becomes a second source of content truth.
5. Producer packages own their structured output schemas.
6. Shared substrate packages own reusable formats and mechanisms, while the instance owns domain vocabulary and policy.
7. Generated metadata packages are refreshed through explicit sync commands and protected by drift checks.

Code orientation

Implementation changes should update this record when they add a component, reverse a dependency, move an ownership boundary, or change a cross-component contract.