Skip to content

Source / Deployment / Runtime Separation

One law nobody is allowed to violate:

Applications are source code. Web is deployment. Docker is runtime. Three completely different responsibilities.

This is the directory-level expression of the Primary Engineering Invariant (Source → GitLab CI → IaC → Runtime; deployment is the product). Related: ADR-0006 (NAS-centric layout decision), Convergence Doctrine §4 (orthogonality), Authority Boundary Rules §2 (environment boundary).

Scope note (2026-08-27): The Mac worktree and NAS share paths below describe the dev-client / custodian topology from ADR-0006. Gas City production runtime is Oracle-only, reached via Tailscale — see oracle-canonical-architecture §0. Do not apply NAS/Mac path rules to Oracle rig bindings.

The Law

Applications is the factory. It contains the intellectual property of the organization: source code, documentation, tests, and build definitions.

web_packages is the warehouse. It contains immutable, versioned artifacts produced by the factory and consumed by deployments.

web is the storefront. It contains deployed applications that serve users. It is an output of the deployment process and is never edited directly.

docker is the machinery. It contains ephemeral runtime infrastructure — containers, volumes, logs, caches, and databases. It exists solely to execute software and can be destroyed and recreated without loss of source or business logic.

The Rule

Directory Owns Never contains
/Volumes/AgentPlatform/Applications NAS application repositories backing Mac worktrees Runtime data
worktrees Disposable Mac worktrees Authoritative source or runtime data
Scratch Temporary and scratch files Authoritative source or documentation
/volume1/web_packages Release artifacts Source code
/volume1/web Deployed applications Git repositories
/volume1/docker Containers, volumes, runtime state Development work

Observed topology [OBSERVED 2026-07-19, SSH listing]

The NAS shares are co-resident on /volume1; the Mac worktree and scratch locations are consumer paths. Scope is explicit so the law is never misapplied:

  • Governed by this law: AgentPlatform/Applications (NAS repository storage) · Mac worktrees (execution workspace) · Mac Scratch (temporary work) · web_packages (warehouse) · web (storefront) · docker (machinery).
  • Governed by other authorities, not this law: AgentPlatform/Knowledge and other non-application shares — Documentation Curation Policy and workspace doctrine.
  • Explicitly out of scope — never reorganized, "cleaned up", or audited under this law: homes/home (user data) · chat · a2a · MinimServer · PlexMediaServer (media) · TimeMachine (backups) · Synology @* system directories.

Applications (the factory)

Everything here is versioned, reviewed, and released through GitLab. Each NAS repository provides durable local Git storage for registered Mac worktrees under worktrees/; authored work occurs in those worktrees and is pushed to GitLab.

  • Allowed: Git repositories · source code · documentation · tests · build scripts · CI definitions · release artifacts only if generated from builds.
  • Not allowed: running websites · databases · uploaded files · SSL certificates · Docker volumes · container state · random backups · media libraries.

The recovery test: "Can a replacement workstation create a fresh worktree from the NAS repository and reconcile it with GitLab?" If yes, the topology is correct.

web (the storefront)

Each directory is deployed output only (e.g. bluefly.io/, agentblu.ai/, copaw.us/, api.bluefly.io/). Nothing is edited here; everything arrives from CI/CD. Editing production in place is a loss condition, not a workflow.

web_packages (the warehouse)

Nothing here is developed; everything is produced: composer/npm packages, module archives, release tarballs, OCI image bundles, Helm charts, static builds. Applications create packages; packages become deployments.

docker (the machinery)

Nothing here is human-managed (compose/, volumes/, service state, logs/, observability). Everything can disappear and be recreated. If deleting it destroys source code, the architecture is wrong.

The Pipeline (one direction only)

Developer → Mac worktree → GitLab → CI/CD → web_packages (versioned artifacts)
          → Deployment → web (running sites) → docker (runtime)

Nothing flows backwards:

  • Never copy production back into Applications.
  • Never edit web.
  • Never develop inside docker.
  • Never commit anything from web_packages.

If everyone follows these four rules, boundaries stay clear, deployments become reproducible, and ownership stays unambiguous.