Internal documentation for contributors. For user-facing docs, see /docs/.
| I want to... | Go to |
|---|---|
| Understand the architecture | knowledge/ |
| Follow coding standards | guidelines/ |
| Learn why we made a decision | adr/ |
| Complete a specific task | guides/ |
| See what's being built | ../specs/ |
| Use agent workflows | ../.agents/skills/ and ../.agents/commands/ |
- specs/: Approved designs at repo root (
../specs/). Living during development, then extracted intoknowledge//guidelines//adr/and moved to../specs/archive/with anEXTRACTED.mdrecord. - guidelines/: Prescriptive rules. How code should be written.
backend/- Python backend standardsfrontend/- React/TypeScript standardscyclopts.md- CLI authoring standards
- knowledge/: Descriptive reference. How the system works.
backend/- Backend (server) architecture and patternsagent/- In-cluster agent and operatorfrontend/- Frontend architecturecli/-styrminctlinternals
- guides/: Step-by-step procedures for specific tasks.
- adr/: Architecture Decision Records. Why we chose what we chose.
- prompts/: Prompt templates for common thinking tasks. Currently empty.
Agent workflows live at the repo root under .agents/skills/ and .agents/commands/.
explorations/ → specs/ → knowledge/ or guidelines/
(rough) (approved) (stable)
Mark deprecated docs clearly. Don't delete—update with pointers to replacements.
- backend/python.md - Python coding standards, tooling, patterns
- frontend/routing.md - TanStack Router conventions:
$paramsyntax, type registration, navigation - frontend/data-fetching.md - TanStack Query + GraphQL codegen: invalidation, polling, conditional fetch
- frontend/forms.md - TanStack Form + Zod: field bindings, subscriptions, dynamic fields
- frontend/ui-primitives.md - Base UI wrapper layer, data-attribute selectors, polymorphic Button
- cyclopts.md - Cyclopts CLI conventions: parameters, validators, type aliases, lazy loading
- helm.md - Styrmin chart rules: requests only, never resource limits
- changelog.md - towncrier newsfragments: types, naming, and how releases assemble CHANGELOG.md
- markdown.md - Markdown conventions and document structure
- 0001-alembic-database-migrations.md - Adopt Alembic for versioned database migration management
- 0002-shared-async-event-loop-kopf-prefect.md - Shared async event loop for kopf operator and Prefect agent
- 0003-leader-election-kopf-peering.md - Priority-based leader election via kopf peering
- 0004-embed-context-in-deployment-crd.md - Embed GlobalContext in StyrminDeployment CRD for autonomous reconciliation
- 0005-ordered-phase-deployment-sub-handlers.md - Ordered phase-based deployment via kopf sub-handlers; the teardown also deletes the Ingresses that Styrmin builds, amended by ADR-090
- 0006-prefect-crd-intent-declaration.md - Prefect flows declare intent via CRD instead of direct resource management
- 0007-pod-status-records-observed-state-not-declared-state.md - Pod-status records observed runtime state, not declared component intent
- 0008-deployment-soft-delete-tombstoning.md - Soft-delete tombstoning with the agent status reporter as the sole writer of
Deployment.deleted_at - 0009-forensic-cr-retention-janitor.md - Forensic-retention CR janitor: TTL-gated reaping of
phase: DeletedCRs, never reapsDeleting-stuck ones - 0010-tombstone-visibility-conflation.md - Tombstoned-record visibility:
NOT_FOUNDconflation on writes + opt-inincludeDeletedfilter on reads - 0011-scoped-tombstone-aware-name-uniqueness.md - Per-environment, tombstone-aware deployment name uniqueness via partial unique index
- 0012-environment-config-fanout.md - Environment-config update — typed
UpdateEnvironmentInput, per-deployment fanout, clean replace - 0013-driver-env-var-consumption.md - Deployment env vars: free-form
dict[str, str], three-scope deepest-wins, consumed driver-side via the values template (no platform post-render injection); superseded in part by ADR-057 - 0014-schema-walking-input-propagation-tests.md - Schema-walking propagation tests for Strawberry input completeness against Pydantic config models
- 0015-frontend-value-transform-boundary.md - Frontend value-transform layer at the GraphQL submit boundary for full-replacement inputs
- 0016-authentication-and-sessions.md - Opaque server-side session tokens with dual transport (HttpOnly cookie + bearer header), 30-day absolute / 7-day idle lifetime, argon2id passwords
- 0017-authorization-model.md - Three-tier role-based authorization (
READ_ONLY/READ_WRITE/ADMIN) with default-denyRequiresAuthenticationextension and per-resolverRequiresRole - 0018-typed-update-deployment-input.md - Typed
UpdateDeploymentInput— list-shaped named-dict fields with typed duplicate detection,parameters-merge asymmetry, shared leaf inputs underconfig/inputs.py - 0019-crd-phase-and-task-callback-coexist.md - CRD phase reports and Prefect task callbacks both write
Deployment.statusvia last-write-wins; CRD phase → status mapping - 0020-separate-crd-status-reporting-mutation.md - Dedicated
reportCrdStatusesmutation alongsidereportPodStatusesto keep observed-state channels orthogonal - 0021-deployment-crd-status-snapshot-table.md - One-to-one
DeploymentCrdStatussnapshot table with JSON conditions/managed-resource counts, mirroring the PodStatus observed-state pattern - 0022-compute-service-fqdns-at-runtime.md - Compute service FQDNs at runtime instead of persisting; both UI resolver and driver-context call sites stay live against the resolved config hierarchy
- 0023-dedicated-mutation-per-observed-state-channel.md - Each observed-state channel gets its own
report<X>StatusesGraphQL mutation rather than overloadingcallback()or bundling channels - 0024-two-pronged-stale-data-cleanup.md - Observed-state tables cleaned via server-side stale-set diff per cycle + FK cascade on deployment delete; agent only sends "active set"
- 0025-capabilities-as-extensible-json-column.md - Cluster/Environment
capabilitiespersisted as JSON column with extensible nested-dict schema{category: {sub: details}}, exposed asJSONGraphQL scalar - 0026-capabilities-recalculation-in-service-layer.md - Capabilities recalculated synchronously in service-layer mutations within the same
UnitOfWork; no triggers, no background tasks, no event bus - 0027-environment-capabilities-computed-independently.md - Environment capabilities computed directly from environment's own config + relationships, not by copying/filtering cluster capabilities
- 0028-deployment-history-derived-from-existing-data.md -
deploymentTimelinequery derives version + context diff at read time from existingTaskandApplicationInstance.contextrows — no schema additions - 0029-config-additions-via-baseconfigsection-no-migration.md - Default pattern for operator-tunable config knobs: add to
BaseConfigSection, no DB migration, no GraphQL schema change — rides existing JSON columns andconfig: JSONmutations - 0030-lockstep-gating-middleware-annotation-and-resource.md - Rendered name-references (e.g., Traefik
router.middlewaresannotation →Middlewareresource) gated on the same condition as their referent; both render or neither does - 0031-dual-identifier-resolution-service-layer.md - GraphQL operations accept
<resource>Id/<resource>Nameoptional pair; service-layerresolve_<resource>helpers validate mutual exclusivity and own the name → entity lookup (AmbiguousIdentifierError) - 0032-resourcespec-first-class-plus-extended-map.md -
ResourceSpectypes CPU/memory/ephemeral-storage as first-class fields plus anextended: dict[str, str]map (hugepages, GPUs, vendor resources) with quantity validation only - 0033-scheduling-merge-semantics.md - Scheduling merge: Environment → Deployment → Component, affinity accumulate with per-kind
replace:true, topology-spread keyed by(topologyKey, whenUnsatisfiable); no cluster-level scheduling (a cluster config rejects it since #482) - 0034-affinity-by-deployment-reference-via-label.md - Affinity-by-deployment-reference expands to a
labelSelectoragainst thestyrmin/deployment_idpod label, stamped byTemplateLabelPatchon every platform-managed pod template - 0035-post-render-injection-toggles-and-kind-list.md - Post-render injection: six per-feature
inject.*booleans at deployment/component scope (no environment scope), patches target a static six-kind list (Deployment,StatefulSet,DaemonSet,Job,CronJob,ReplicaSet) - 0036-scheduling-provenance-map.md - Resolved scheduling carries a parallel
provenance: dict[str, "environment" | "deployment" | "component"]map keyed by dotted paths so operators can see which level contributed each value - 0037-sdk-typed-bindings-outer-wrapper-and-facade.md - SDK keeps
Transport.execute()+load_query(), swaps hand-written models for ariadne-codegen outer-wrapper validation, re-exports canonical names frommodels/__init__.pyas a facade - 0038-scenario-driver-protocol-and-parametrized-fixture.md - E2E
ScenarioDriverProtocol with API/UI implementations + parametrized fixture; one scenario body produces[api-chromium]and[ui-chromium]variants;-kis the single selection axis - 0039-single-cluster-platform-scope.md - Platform is single-cluster — enforced at service layer (
ClusterLimitReachedError), no DB constraint, default name"default"; multi-cluster is a future architectural project - 0040-cosign-keyless-image-signing.md - Container images signed with cosign keyless via GitHub Actions OIDC; sign by digest, not tag; one signature on the multi-arch manifest list covers all architectures
- 0041-release-workflow-orchestration.md - Release pipeline split into
release.ymlorchestrator + reusable child workflows (docker-publish.yml,publish-helm-chart.yml); static concurrency group withcancel-in-progress: falseso an in-flight release is never killed mid-write - 0042-multiarch-via-native-runner-matrix.md - Multi-arch Docker built on native runners (
ubuntu-24.04+ubuntu-24.04-arm64) via a matrix +imagetoolsmanifest merge, not QEMU emulation; per-arch pushes by digest only, manifest signed as one - 0043-docs-site-and-documentation-lifecycle.md - User-facing docs live in Docusaurus at
docs/;dev/knowledge/,dev/guides/,dev/adr/stay contributor-internal; promotion fromdev/todocs/is a deliberate authoring step, not automatic extraction - 0044-e2e-matrix-sharding.md - E2E parallelism via CI matrix shards (one vCluster per shard, bare-name shard markers enforced at collection), not pytest-xdist
- 0045-container-override-no-layering-and-omit-marker.md - Component-scope
command/args: no layering, empty-list marker with a chart{{- with }}guard (the omit-marker broke clearing under merge-patch), per-field typed errors; merge-patch apply narrowed by ADR-057; §2 and §5 superseded by ADR-069 - 0046-tombstone-cleanup-of-deployed-services.md - Delete
DeployedServicerows when a deployment is tombstoned so a redeploy does not collide on service name - 0047-styrminctl-anonymous-fire-and-forget-telemetry.md - Anonymous opt-out CLI telemetry: closed key set scrubbed by construction, daemon-thread dispatch with a hard 200 ms cap, default-on but silent with CI/non-TTY exclusion
- 0048-declarative-apply-client-side-orchestration.md - Declarative apply is orchestrated client-side in the SDK over the existing
deploy/updateDeployment/updateDeploymentVersionmutations; config before version, one re-lookup on a duplicate-name race - 0049-styrmin-v1-manifest-contract.md - The
styrmin/v1manifest: strictextra="forbid"parsing, full replacement ofconfig/parameters, flag > env > manifest precedence,clusteras a disambiguation hint, deliberately not kubectl-compatible - 0050-composite-natural-key-deployment-lookup.md -
deployment(name, environmentId)composite natural-key shape with a runtime argument-group guard; the bounded carve-out from ADR-031's<resource>Id/<resource>Namepattern - 0051-styrminctl-credential-resolution-and-token-store.md - CLI credential ladder (env > auto-login > file > none) resolved at one chokepoint, plus the versioned, canonical-URL-keyed, atomically-written token store
- 0052-client-side-config-diff-impact-and-conflict-detection.md - Deployment config drawer: hand-rolled stable-key structural diff, declarative impact rule table behind a swappable interface, client-side fingerprint conflict detection with reload-keeping-edits
- 0053-driver-version-provenance-fingerprint.md - Driver-version identity widens to include a provenance fingerprint (
content_hashfor local,source_commit_shafor git); no load ever deletes a row; labels always render<version>@<short7> - 0054-backend-authoritative-noop-detection.md - No-op detection runs in the service layer before any write and is signalled by returning
nullfrom the already-nullableTaskfield; reverts the SDK-side stopgap - 0055-environment-backup-parent-records.md - Environment backup/restore as parent records grouping constituents via nullable child FKs, with status derived on every read and never stored; the justified deviation from ADR-012's umbrella rejection, plus the restore ordering that excludes restored deployments from the config fan-out
- 0056-environment-clone-record-and-cross-target-restore.md - Environment clone as a first-class
EnvironmentClonerecord with derived status, built from a fresh environment backup and a cross-target restore (VeleronamespaceMapping) into counterpart deployments that keep the source's Helm release name; a waiting INTERNAL flow;IN_USEdelete guard limited to the capture window - 0057-post-render-component-overrides.md - Drivers declare a component container per component; env vars merge into it by a strategic-merge post-render patch (chart entries survive),
component_env_varsretired, Styrmin-managed HelmReleasespeckeys replaced on update; wrong-name failure narrowed by ADR-058 - 0058-image-overrides-and-component-container-guard.md - Per-component image overrides (
{{ app.version }}substitution, hand-written reference grammar) applied to the component container by post-render; one JSON6902 guard for env vars and images fails a misnamed container withCOMPONENT_CONTAINER_NOT_FOUNDinstead of adding one; upgrade re-validation;get_component_imagesreturns the component container's image first; extended tocommand/argsby ADR-069 - 0059-driver-action-api-tokens.md - Driver actions call the API as the built-in
styrmin-actionsuser (READ_WRITE, no password) with a session thatapply_statecreates per reconcile, passes down inSTYRMIN_TOKENthrough Prefect job variables, and deletes when the reconcile ends; no allow-list or schema change - 0060-steps-and-derived-task-result.md - Steps of tasks, backups and restores are written only through the step recorder, by server code and INTERNAL flows directly, by USER flows and actions through
recordStep(styrmin-actionsonly), and by operator reports linked throughstatus.instanceId; the task result is derived from the task's family on every read; the operator judges the HelmRelease on its current generation;run_job, backups and restores get action tokens - 0061-server-anonymous-daily-telemetry.md - The server side sends one anonymous report a day from an INTERNAL cron flow in the task worker, in the
styrminctlenvelope withkind: "styrmin"; driver names are sent as written; the install ID is stored in the single-rowinstallationtable; runs that start more than one hour late send nothing;STYRMIN_WORKFLOW_ENABLEdoes not stop it - 0062-backup-history-derived-through-instances.md - A deployment's backup history is every backup of any of its instances, read by joining
BackuptoApplicationInstance;backupstakes exactly one ofdeploymentIdorinstanceId; noBackup.deployment_idcolumn - 0063-restore-of-earlier-instance-backup.md - Restoring a backup of an earlier instance puts that instance's resources back and keeps the active instance; the Backups tab warns,
restore --lastasks for confirmation (--yes) and skips expired backups; the server refuses a restore into a deleted deployment - 0064-styrmindeployment-write-order-by-instance-sequence.md - Each instance gets a per-deployment
sequencefromdeployment.last_instance_sequence, incremented under the deployment row lock when the repository saves it; the StyrminDeployment records it instyrmin.io/instance-sequence, and a flow leaves a StyrminDeployment that holds a higher sequence unchanged - 0065-apply-writes-config-with-the-version.md -
updateDeploymentVersiontakes an optionalinputvalidated against the target driver and application versions and written with the version in one task;styrminctl applysends one such call per existing deployment; upgrade task only on a version or binding change; services recreated only when they change - 0066-cluster-config-fanout.md - The cluster config fan-out redeploys each deployment whose resolved config differs from its active instance's (not ADR-012's comparison of one config level); applications move onto a dedicated ingress controller only once it is
RUNNING, continued by the status reporter, and the controller is removed once no application depends on it (which also applies after an environment update); typedUpdateClusterInputwhilecreateClusterkeeps JSON;updateClusterreturns the redeployed, waiting and failed deployments and has adryRun; each environment commits on its own, and a nestedasync with uowthat fails inside a savepoint rolls back only that savepoint (uow.commit()inside a savepoint raises); the SDK refuses unknown config keys - 0067-driver-logos-loaded-by-the-viewer-browser.md - A driver logo is an
httpsURL stored per driver version and loaded by each viewer's browser through<img>with no referrer; Styrmin never fetches or proxies it;STYRMIN_DRIVER_SHOW_LOGOS=falsemakes the API return no icon - 0068-invalid-driver-info-dropped-with-load-warning.md - An invalid
spec.infoicon or link is dropped and the load returns a warning inloadWarningsinstead of failing; replaces research R3 of spec 020 - 0069-container-command-args-by-post-render.md - Container
command/argsoverrides are applied by the post-render merge patch (renamedContainerMergePatch) and guard to the component container; oneoverride_appliesrule for the patch builder, action primitives andisApplicable;component_command/component_argsretired withRETIRED_TEMPLATE_FILTER;COMPONENT_CONTAINER_NOT_DECLAREDextended tocommand/args;spec.container_overridesremoved from the driver format, database and API; supersedes ADR-045 §2 and §5 - 0070-replica-overrides-and-retired-parameters.md - Per-component replica overrides stored in
ComponentConfigBlock.replicasand applied by one post-renderspec.replicaspatch per kind per component, which also carries the stopped state (replaces the component state patch of ADR-057 §2); order of precedence override, then driver default (replicas, or 1 forsingleton: true), then the chart's count;UNKNOWN_COMPONENT_REPLICA_OVERRIDEandSINGLETON_REPLICA_OVERRIDEagainst the driver version bound after the write; on a driver version change a parameter the target no longer declares is dropped at its current default (same type) and otherwise rejected withRETIRED_PARAMETER_VALUE - 0071-ingress-class-set-by-post-render.md - With a dedicated ingress controller, a strategic merge patch removes
spec.ingressClassNamefrom every application Ingress after the chart renders (a JSON6902removefails on an absent field), instead of an IngressClass per controller;ingress_classstays in the values-template data in both modes; with no class resolved, the chart's class stays; driver templates set no class; superseded in part by ADR-090 (the premise that a chart renders every Ingress) - 0072-helm-v4-defaults-releases-keep-apply-method.md - helm-controller runs without
UseHelm3Defaults, so new installs use server-side apply with forced conflicts, installs and upgrades wait with kstatus, and Helm hooks receive Styrmin's post-render patches (combined); upgrades and rollbacks keepauto, so releases installed with the gate keep client-side apply and releases installed without it keep server-side apply if the gate is turned on again; the every-resource label patch becomes a strategic merge so a resource withoutmetadata.labelsno longer fails the render; the operator's rules do not change - 0073-kubernetes-objects-named-and-found-by-record-id.md - Every Kubernetes object that Styrmin creates for a record is named after the record's id and carries an id label; updates and deletes find it by that label or by the id-based name, never by a name a user can change; flows that act on cluster objects take the id
- 0074-bsl-keys-passed-to-flows-in-prefect-secret-block.md - The server saves a backup storage location's S3 keys in the Prefect Secret block
styrmin-bsl-<id>-credentialsand passes only the id to thesync-bslflows, which load the keys from the block; the value is a JSON string so Prefect API reads hide it; deleting the location deletes the block - 0075-deployment-references-stored-by-id.md - A deployment reference in a pod affinity or pod anti-affinity term is stored as the named deployment's id: every write that stores a config replaces a name with the id, and refuses a term that names a deployment the environment does not have or a tombstoned deployment with
VALIDATION_ERRORand the term's path; each reconcile resolves the id tostyrmin/deployment_id=<id>, so a rename changes no term; an environment clone points the copied terms at its counterpart deployments and refuses a request whose copied terms name a deployment it does not copy; an environment restore writes the captured config back unchanged; amends ADR-034 - 0076-teardown-deletes-service-aliases-in-all-namespaces.md - The operator's teardown first deletes the deployment's service aliases in all namespaces, found by the
styrmin.io/deployment-idlabel or, without it, by the namespace thatspec.externalNamepoints into; it acts only when the CR's namespace isstyrmin-<spec.deploymentId>, and, withoutspec.deletionRequested, only while the namespace exists and is notTerminating, so a restore's namespace deletion deletes no alias; deletes carry the listing'sresourceVersionand are best-effort - 0077-alias-flow-reads-deletion-state-at-write-time.md - The alias flow reads each Namespace and StyrminDeployment before it writes and skips departing namespaces, reads again after it writes and deletes the aliases it wrote for a deployment whose deletion started in between, and never creates a namespace; one case can leave an alias, which the maintainer accepted
- 0078-alias-step-reads-current-services-from-server.md - The alias step reads the other deployments' services from the server with the flow's action token, because a flow's context lists no deployment requested after it; the deployment's own services and the templates' context stay as built; a deployment changed while a peer is restored gets no aliases to it until a later change
- 0079-driver-actions-import-only-from-their-driver-directory.md - Each action of a driver version loaded from a driver directory runs from it through Prefect's
set_working_directorypull step, soactions.pyimports modules only from its driver directory and the action's image; every git load, from a driver directory or the repository root, refuses a driver directory or driver file whose real path is outside the clone - 0080-action-deployments-keyed-by-driver-directory.md - The Prefect deployment of each action of a driver version loaded from a driver directory carries a
directory/<driver directory>tag and a 12-character SHA-256 digest of the driver directory in its name, so two driver versions loaded at one commit keep separate actions; root driver versions keep their names and tags, and a lookup for one drops deployments that carry adirectory/tag - 0081-local-driver-actions-check-their-files-at-the-driver-path.md - The actions of a driver version loaded from a local directory are registered under its path (
action_directory_of) and run theactions.pyat that path, after a pull step that checks the files there against the driver version's provenance fingerprint; a local path with{or}is refused for a driver with actions; the firstERRORlog of a crashed action goes into its hook step's error; a declared action without a registered flow fails its hook step (inapply_state, or in a request check ofupdate_deployment_versionthat changes nothing) instead of being skipped, and loading the driver again registers the missing actions; actions run in the agent pod, where an action'simage:has no effect - 0082-recorded-demos-reuse-e2e-page-objects.md - The recorded demos live in
backend/tests/e2e/demos/and act in the Styrmin UI only throughUiScenarioDriverand the E2E page objects, with no selector for a Styrmin page; page objects takekeystroke_delay_msand enter text withenter_text, so the demos type one key at a time and the E2E suite keepsfill(); CI does not run the demos, E2E tests call the page-object methods they added, and the command has an owner and a schedule for recording again - 0083-demo-waits-sped-up-after-recording.md - Each demo is recorded as one Playwright 1.64 screencast with chapters, a cursor and a highlight; the recorder records the start and end of each wait and each cut, a pure
plan_segmentsspeeds each long wait up to at most 4 s, labels are PNG images that the browser renders and ffmpeg overlays, the video is H.264 MP4 at 1920×1080, andplan.jsonlets a failed encoding run again without recording again - 0084-record-command-deletes-only-environments-it-created.md - The record command records the ids of the environments it creates in
$XDG_STATE_HOME/styrmin/demo-environments.json, for each demo stack URL, and deletes only those; it asks on the terminal before it deletes another environment with a demo's name, and without a yes or a terminal it stops before any change - 0085-restore-target-derived-from-the-backups-deployment.md -
createRestoretakes only the backup id;resolve_restore_targetdecides where every restore lands,styrmin-<deployment id>of the backup's deployment or of an environment clone's counterpart, andcreate_restorerecords that namespace and the deployment's active instance; the restore flow fails a restore whose namespace is not its deployment's before it changes the cluster;styrminctl backups restoreaccepts the target options only with--last - 0086-removed-graphql-arguments-explained-to-older-clients.md -
ExplainRemovedArgumentsreplaces graphql-core'sKnownArgumentNamesRuleso that a client older than the server is told that an argument listed inREMOVED_ARGUMENTSwas removed and to upgrade; the Python SDK raisesIncompatibleServerErrorwhen an older server still requires an argument the SDK no longer sends - 0088-pod-status-entries-for-init-containers-and-scheduling.md - The agent stores a pod's init containers and, for a pod that is not scheduled, its
PodScheduledcondition as entries ofcontainerStatuseswith akind(pod,init,sidecar,container) and the kubelet's or the scheduler'smessage; a failed operator-phase step names any reason except a starting one, a container that runs again after restarts, an init container that is still running, and a sidecar that is not ready - 0090-styrmin-builds-the-ingress-of-an-external-service.md - Styrmin builds one Ingress for each service that a driver declares
scope: external(httporhttps) and the chart renders none; it is namedstyrmin-svc-<driver service name>and labeled with the driver service name, an exception to the wording of ADR-073; a per-service ingress class and FQDN suffix override is stored inDeploymentConfig.serviceswith no database column, and an overridden Ingress carries the class only; every external service gets the readable host and only the first declared service, when external and not overridden, gets the application address; an override on a service that is not external or not declared, and a driver version change that would drop an override, are refused with an error that names the service; the operator lists, restores and deletes the built Ingress and never touches a chart Ingress; supersedes the part of ADR-071 that assumes a chart renders every Ingress
- architecture.md - High-level system architecture: server↔agent topology, declarative state, context model. Companion to the constitution.
Backend (server) architecture documentation in knowledge/backend/:
- overview.md - Architecture overview, directory structure, request flow
- api.md - GraphQL API (public and internal), types, response patterns
- data-models.md - Database, domain, and context models
- services.md - Service layer, unit of work, business logic
- reconciliation.md - Reconciliation engine, diff computation, remediation strategies
- hooks-and-actions.md - Hook system, driver actions, setup/upgrade hooks
- orchestration-flows.md - Prefect orchestration flows, callbacks, execution patterns (the server chart's task-worker runs the INTERNAL flows; the agent's Prefect worker runs the USER flows and driver actions)
- backup-restore.md - Backup/restore system, Velero integration, strategies, retention TTL, environment-level backup and restore, environment clone and the cross-target restore
- deployment-env-vars.md - Deployment env vars: when to use them, three-scope precedence, post-render injection into the component container
- e2e-testing.md - E2E testing architecture, vCluster fixture graph, markers, debugging workflow
- dead-code.md - Remaining dead code and cleanup tracking
Agent (in-cluster) architecture documentation in knowledge/agent/:
- overview.md - Agent process layout, where Prefect lives, Kubernetes resource builders, status reporter
- operator.md - Kopf operator, StyrminDeployment CRD, phase-based deployment, drift reconciliation
Frontend architecture documentation in knowledge/frontend/:
- routing.md - TanStack Router architecture, route tree, type registration, lazy routes
- data-fetching.md - TanStack Query + codegen pipeline, fetcher, cache invalidation, polling
- forms.md - TanStack Form architecture, Zod integration, field bindings, dynamic fields
- ui-primitives.md - Base UI wrapper layer, Slot utility, data-attribute conventions
- deployment-configuration.md - Configuration tab and edit drawer: draft lifecycle, diff → impact → apply, inheritance state, conflict detection
- deployment-timeline.md - History timeline and backup/restore rows: task result badges, step rows, output loaded on request, entry expansion and task links, E2E data attributes
- environment-backups.md - Backups and Clones tabs of the environment detail page: roles, polling, invalidated queries, the discard label
- driver-pages.md - Driver list and detail pages:
DriverLogostates, where the logo, description and links appear, load warnings
CLI (styrminctl) internals in knowledge/cli/:
- overview.md - Invocation pipeline, credential chokepoint, token store, error boundary, telemetry wrapper
- database-migrations.md - Alembic migration workflow: creating, applying, and rolling back migrations
- graphql-propagation-tests.md - How to write the unit test that proves a GraphQL field is wired through every layer to the database
- pre-commit-hooks.md - Installing the
prekhooks, what each one runs, and the bypass policy - bug-pipeline.md - End-to-end bug workflow: analyse, reproduce, fix, verify
- local-demo.md - Local vCluster demo lifecycle
- driver-iteration.md - The no-bump loop: editing a driver and reloading without changing its version string
- driver-env-var-consumption.md - How a driver declares the component container that receives user env vars by post-render patch
- pod-scheduling.md - Pod scheduling configuration reference
- ingress-ipv6-dual-stack-validation.md - Validating ingress and NodePort behaviour on dual-stack clusters
- e2e-parallelism.md - The five-shard CI matrix scheme and how shard markers route tests
- e2e-deployment-sharing.md - Decision tree for reusing an existing E2E deployment instead of booting a new one
- session-retrospectives.md - End-of-session workflow for turning agent friction into approved context-management improvements
- users-and-groups.md - Operator guide to users, groups, roles, the bootstrap admin, the Settings → Access UI, lockout recovery, and v1 limitations