refactor: reorganize GitOps control plane

docs/architecture/deployment.md

@@ -0,0 +1,55 @@
+# Deployment architecture
+
+## Reconciliation boundaries
+
+```text
+Gitea main
+  |
+  +-- Argo CD root -> AppProjects + child Applications -> Kubernetes
+  |
+  +-- approved Terraform runner -> Vault API
+```
+
+Argo CD는 Kubernetes desired state만 관리합니다. 최초 Argo 설치/root
+seed와 문서화된 recovery 외에는 직접 cluster mutation을 하지 않습니다.
+Terraform은 Config Management Plugin이나 Argo hook 안에서 실행하지
+않습니다.
+
+## Kustomize ownership
+
+- `platform/`, `workloads/`: 환경 중립 base
+- `clusters/dev-k3s/manifests/`: namespace, host, image, Vault role 및
+  NetworkPolicy를 포함하는 최종 cluster composition
+- Argo CD Application: final composition만 source로 사용
+
+지원하지 않는 production overlay는 존재하지 않습니다. production
+계약과 승인 경계가 확정될 때 별도로 생성합니다.
+
+## In-application ordering
+
+`auth-server`의 한 sync operation 안에서:
+
+- generated ConfigMap과 일반 리소스: wave `0`
+- database migration Sync hook: wave `5`
+- Deployment: wave `10`
+- north-south route: wave `20`
+
+`auth-system`의 Keycloak client sync도 idempotent Sync hook이며 deadline,
+backoff, `BeforeHookCreation,HookSucceeded` cleanup을 사용합니다.
+
+## Stateful lifecycle
+
+Vault와 PostgreSQL PVC는 `Prune=false`로 보호합니다. child Application
+prune/delete는 확인이 필요합니다. path 이동이나 Application rename 전에는
+새 owner가 동일 live resource를 정상적으로 추적하는지 확인한 후 이전
+owner를 non-cascading 방식으로 제거합니다.
+
+## Image promotion
+
+첫-party image는 애플리케이션 CI가 얻은 정확한 GHCR digest를 Gitea
+workflow에 전달합니다. workflow는 digest 변경 PR을 만들고, validation과
+승인을 거쳐 merge된 뒤 Argo CD가 배포합니다.
+
+현재 short-SHA tag는 migration 시점의 예외입니다. private GHCR을 읽을
+자격증명이 이 저장소 실행 환경에 없으므로 임의 digest로 바꾸지 않았고,
+다음 정상 promotion에서 `digest:`로 교체됩니다.