commit 11276575c34e3121bdd701ddc0d292b9e31a904c
Author: u1 <u1@rv32i.pl>
Date:   Sun Apr 12 11:44:56 2026 +0000

    docs(architecture): add k3s component to repository map

diff --git a/doc/k3s-component-repo-map.md b/doc/k3s-component-repo-map.md
new file mode 100644
index 0000000..29c6176
--- /dev/null
+++ b/doc/k3s-component-repo-map.md
@@ -0,0 +1,112 @@
+# K3s Component To Repository Map
+
+## Purpose
+
+This document is the canonical map of the current trade stack running on `k3s` and the repository boundaries in `trade-next`.
+
+It answers one question:
+
+- which live `trade-staging` component belongs to which repository
+
+## Repository Set In `trade-next`
+
+- `trade-api`
+- `trade-frontend`
+- `trade-ingestor`
+- `trade-bot`
+- `trade-dlob`
+- `trade-gitops`
+- `trade-host-iac`
+- `trade-docs`
+
+## Ownership Rules
+
+- Application code belongs to the application repository.
+- Kubernetes manifests, image wiring, services, ingresses, configmaps, jobs, and overlays belong to `trade-gitops`.
+- Host bootstrap, storage layout, `k3s` installation, SSH, WireGuard, and host operations belong to `trade-host-iac`.
+- Cross-repository architecture and operating policy belong to `trade-docs`.
+
+## Live `trade-staging` Component Map
+
+### `trade-frontend`
+
+- Live component: `Deployment/trade-frontend`
+- Code repository: `trade-next/trade-frontend`
+- Deploy repository: `trade-next/trade-gitops`
+- Host/IaC repository: `trade-next/trade-host-iac`
+- Notes: frontend runtime policy, ingress wiring, auth wiring, and image selection belong to GitOps.
+
+### `trade-api`
+
+- Live component: `Deployment/trade-api`
+- Code repository: `trade-next/trade-api`
+- Deploy repository: `trade-next/trade-gitops`
+- Host/IaC repository: `trade-next/trade-host-iac`
+- Notes: API wrapper, runtime env, and service exposure belong to GitOps.
+
+### `trade-ingestor`
+
+- Live component: `Deployment/trade-ingestor`
+- Code repository: `trade-next/trade-ingestor`
+- Deploy repository: `trade-next/trade-gitops`
+- Host/IaC repository: `trade-next/trade-host-iac`
+- Notes: the current live system still mixes app image and deploy-injected runtime logic; this boundary must be cleaned up during migration.
+
+### `trade-dlob`
+
+- Live components:
+- `Deployment/dlob-publisher-hot`
+- `Deployment/dlob-publisher-all`
+- `Deployment/dlob-hot-redis-to-postgres-raw-writer`
+- `Deployment/dlob-hot-postgres-to-postgres-derived-writer`
+- `Deployment/dlob-all-redis-to-postgres-derived-writer`
+- Future or optional component: `Deployment/dlob-server`
+- Code repository: `trade-next/trade-dlob`
+- Deploy repository: `trade-next/trade-gitops`
+- Host/IaC repository: `trade-next/trade-host-iac`
+- Notes: all DLOB publishers, stream processors, and writers belong to the same application family and should stay in one code repository.
+
+### `dlob-redis`
+
+- Live component: `Deployment/dlob-redis`
+- Code repository: none, external image
+- Deploy repository: `trade-next/trade-gitops`
+- Host/IaC repository: `trade-next/trade-host-iac`
+- Notes: Redis topology, persistence mode, service wiring, and operational policy belong to GitOps and host IaC, not to an application repository.
+
+### `hasura`
+
+- Live component: `Deployment/hasura`
+- Code repository: none, external image
+- Deploy repository: `trade-next/trade-gitops`
+- Host/IaC repository: `trade-next/trade-host-iac`
+- Notes: bootstrap scripts, metadata policy, secrets wiring, and service exposure belong to GitOps.
+
+### `postgres`
+
+- Live component: `StatefulSet/postgres`
+- Code repository: none, external image
+- Deploy repository: `trade-next/trade-gitops`
+- Host/IaC repository: `trade-next/trade-host-iac`
+- Notes: schema bootstrap and Kubernetes object ownership belong to GitOps, while disk placement, quotas, storage class policy, and backup policy belong to host IaC.
+
+### `trade-bot`
+
+- Live component: none observed as a separate deployment in the current `trade-staging` state
+- Code repository: `trade-next/trade-bot`
+- Deploy repository: `trade-next/trade-gitops` when introduced as live runtime
+- Host/IaC repository: `trade-next/trade-host-iac`
+- Notes: this repository exists in the target design even if it is not yet represented by a dedicated live deployment.
+
+## Boundary Summary
+
+- App repositories: `trade-api`, `trade-frontend`, `trade-ingestor`, `trade-bot`, `trade-dlob`
+- Cluster source of truth: `trade-gitops`
+- Host and infrastructure source of truth: `trade-host-iac`
+- Documentation source of truth: `trade-docs`
+
+## Current Drift Notes
+
+- The current live cluster is not yet fully described by the local repos we audited.
+- The historical `trade-deploy` and host-side `trade-k8s` layouts do not cleanly match the current live `trade-staging` shape.
+- During migration into `trade-next`, this document should be updated whenever a component boundary changes.