From 29bc8e1a58315981e7bff547f6c0191e8272921c Mon Sep 17 00:00:00 2001
From: Tyler Gillispie <mrteye@gmail.com>
Date: Sun, 23 Aug 2026 10:23:37 -0700
Subject: [PATCH] docs: clarify custom project images vs upstream open-source
 infrastructure in COMPOSE_CONVENTIONS.md

---
 COMPOSE_CONVENTIONS.md | 35 ++++++++++++++++-------------------
 1 file changed, 16 insertions(+), 19 deletions(-)

diff --git a/COMPOSE_CONVENTIONS.md b/COMPOSE_CONVENTIONS.md
index ad0e648..105b225 100644
--- a/COMPOSE_CONVENTIONS.md
+++ b/COMPOSE_CONVENTIONS.md
@@ -60,49 +60,46 @@ across our infrastructure.
 
 ## 3. Container Registries, Mirrors & Image Distribution
 
-Our infrastructure uses a tiered registry architecture to balance local caching,
-private custom image hosting, and universal build portability:
+Our infrastructure uses a tiered registry architecture to clearly separate
+custom application images from upstream cached dependencies:
 
 ### 3.1 Registry Tier Classification
 
 1. **Primary Custom Image Registry (`${REG}` $\rightarrow$ `quay.atyg.org`):**
-   - Hosts all internally built, project-specific custom images
-     (`${REG}/library/<image>:<tag>`).
-   - Examples: `${REG}/library/auth-yes-api:latest`,
-     `${REG}/library/spire-server:latest`, `${REG}/library/spire-agent:latest`.
-   - Retention policy is set for **indefinite storage** (auto-pruning disabled).
+   - Hosts all internally built, project-specific custom application images
+     (`${REG}/library/<app>:<tag>`).
+   - Example: `${REG}/library/auth-yes-api:latest` (built from project source).
+   - Retained **indefinitely** on disk (auto-pruning disabled).
 2. **Docker Hub Pull-Through Cache (`acr.atyg.org`):**
-   - Proxies and indefinitely caches upstream Docker Hub images on the local
-     network.
+   - Proxies and indefinitely caches upstream Docker Hub infrastructure images
+     on the local network.
    - Examples: `acr.atyg.org/library/postgres:18-alpine`,
      `acr.atyg.org/valkey/valkey:8-alpine`, `acr.atyg.org/library/alpine:3.20`.
 3. **GHCR Pull-Through Mirror (`${GHCR_REG}` $\rightarrow$ `ghcr.atyg.org`):**
-   - Proxies and caches GitHub Container Registry packages.
+   - Proxies and caches upstream GitHub Container Registry infrastructure
+     images.
    - Examples: `${GHCR_REG}/spiffe/spire-server:1.9.3`,
      `${GHCR_REG}/spiffe/spire-agent:1.9.3`.
 
 ### 3.2 Universal Dockerfile Portability (Jules & External CI)
 
-- **Public Upstream Defaults:** Dockerfiles must declare public upstream
-  registries by default so external agents (like Jules) and cloud CI runners can
-  build without private `.atyg.org` DNS:
+- **Public Upstream Defaults:** Dockerfiles for custom application images or
+  wrappers must declare public upstream registries by default so external agents
+  (like Jules) and cloud CI runners can build without private `.atyg.org` DNS:
   ```dockerfile
-  ARG SPIRE_UPSTREAM=ghcr.io/spiffe/spire-server:1.9.3
   ARG BASE_IMAGE=alpine:3.20
-
-  FROM ${SPIRE_UPSTREAM} AS upstream
   FROM ${BASE_IMAGE}
   ```
 - **Local Build Acceleration:** Local builds and CLI scripts (`infra/setup.ts`)
   can optionally pass `--build-arg` to pull through local mirrors
   (`ghcr.atyg.org`, `acr.atyg.org`).
-- **Push Destination:** Custom built images are tagged and pushed to the local
-  authority `${REG}/library/...` (`quay.atyg.org`).
+- **Push Destination:** Custom built application images are tagged and pushed to
+  the local authority `${REG}/library/...` (`quay.atyg.org`).
 
 ### 3.3 Compose Variable Cleanliness
 
 - **No Inline Defaults:** Always write clean variable references in Compose
-  files (`image: ${REG}/library/spire-server:latest`,
+  files (`image: ${REG}/library/auth-yes-api:latest`,
   `image: ${GHCR_REG}/spiffe/spire-server:1.9.3`).
 - **Centralized Values:** Default registry variables belong strictly in `.env`
   and `infra/setup.ts`.