App module

Source: modules/app/ (ce module); the licence/runtime gates overlay lives in this repo’s modules/app/.

modules/app/
├── extractor.go
├── archive_source.go
├── command.go
├── compose.go
├── compose_exec.go
├── compose_remote.go
├── compose_render.go
├── compose_types.go
├── context.go
├── definition.go
├── deployment_tracker.go
├── docker_env.go
├── enrich.go
├── errors.go
├── events.go
├── git_source.go
├── graph.go
├── hooks.go
├── ingress.go
├── ingress_ops.go
├── ingress_parser.go
├── inspection.go
├── install_flow.go
├── integration.go
├── integration_resolve.go
├── lifecycle.go
├── live_progress.go
├── models.go
├── network_ops.go
├── normalize.go
├── path_source.go
├── platform.go
├── queries.go
├── query_ops.go
├── rendering.go
├── router.go
├── scale.go
├── schedules.go
├── service.go
├── service_model.go
├── source.go
├── state.go
├── swarm.go
├── swarm_preflight.go
├── sync.go
├── template.go
├── models.go
├── update_flow.go
├── validate.go
├── vapp.go
├── vapp_flow.go
├── variables.go
├── vars_typed.go
└── commands/

Routes are listed in the generated route reference; request/response notes live in the API reference.

Event codes, durability class, and payload shapes are listed in the generated event reference.

Typed errors are catalogued in the error code reference with HTTP statuses and message templates.

The app module is the largest subsystem in SHC and owns everything about turning an app directory into a running stack and back. It is the source of truth for:

• App definitions. definition.go parses and validates app.yaml (name, version, vars schema with typed fields like @string / @port / @secret, hooks, category). validate.go enforces the schema; errors.go carries a typed error for every way an app can be malformed.
• Rendering. compose_render.go, template.go, and rendering.go render the Go template compose.yaml / stack.yaml templates with the resolved vars (including ref+vault://... secret references). Output is a concrete Compose/Swarm spec.
• Sources. source.go, git_source.go, path_source.go, archive_source.go resolve where an app comes from (local path, git URL, archive), then copy it into the tenant/stack working directory.
• Lifecycle. lifecycle.go + install_flow.go + update_flow.go orchestrate install, upgrade, and uninstall, wiring in pre/post hooks, DNS, ingress, vault, backups, scaling, and Docker network creation. Hooks (hooks.go) run user-provided shell/job steps at every phase.
• Compose / Swarm. compose.go, compose_exec.go, compose_remote.go, swarm.go, swarm_preflight.go are the actual Docker / Swarm invocations. Remote variants tunnel through the internal API to a node that owns the stack.
• VApps, sockets, plugs. vapp.go, vapp_flow.go implement the Virtual-App composition model — apps that extend other apps (e.g. the acme VApp adding TLS to Traefik). integration.go and integration_resolve.go wire declarative dependencies at install time.
• Persistent state. models.go defines AppModel (catalog entries) and DeploymentModel (installed instances); state.go and queries.go handle all database reads/writes.

What the app module does not own: starting/stopping a running stack (that is stack), scheduled jobs (that is job), backups (that is backup), or multi-node placement decisions (that is cluster + node). The app module produces the definition and the filesystem layout; other modules operate on them.

The single public service class is StackService in service.go. It reaches out to backup, clone, cluster, dns, events, export, job, metrics, network, node, quota, repo, schedule, stack, and storage — reflecting the “app” being the crossroads of the entire platform. This is by design: one place owns the full install/upgrade/ uninstall pipeline; everything else is a supporting subsystem.