# Repository taxonomy

이 문서는 새 리소스를 어느 디렉터리에 둘지 결정하는 기준입니다. 이
저장소는 Project Auth를 예제로 삼는 독립 reference lab이며, 디렉터리
이름은 조직의 중요도나 설치 순서가 아니라 소유권을 표현합니다.

## 분류 기준

| 분류 | 판단 질문 | 현재 예 |
|---|---|---|
| `gitops/platform` | GitOps control plane이거나, 둘 이상의 system이 독립 lifecycle로 소비할 cluster capability인가? | Argo inventory, Vault shared service |
| `gitops/apps/systems` | 하나의 bounded context가 함께 소유하는 backing system인가? | Project Auth의 PostgreSQL, Keycloak, realm/client sync |
| `gitops/apps/workloads` | 별도 source repository에서 빌드하는 first-party 실행 단위인가? | `auth-server`, `api-server` |
| `gitops/clusters` | 특정 클러스터의 최종 composition 값인가? | namespace, host, digest, Vault role, NetworkPolicy |
| `infrastructure` | Kubernetes가 아닌 외부 API 객체를 선언하는가? | Vault mounts, policies, auth roles, database roles |
| `bootstrap` | GitOps controller가 존재하기 전에 필요한 최소 seed인가? | Argo CD 설치 버전, 제한된 control-plane AppProject와 root Application |

다음 세 질문을 순서대로 사용합니다.

1. 누가 소비하고 장애 영향을 받는가?
2. 누가 변경을 승인하고 lifecycle을 책임지는가?
3. 다른 bounded context와 독립적으로 교체하거나 배포할 수 있는가?

제품 이름만으로 분류하지 않습니다. 예를 들어 Keycloak이 여러 system의
공용 identity service가 되고 별도 owner와 release cadence를 갖게 되면
실행 서비스는 `gitops/platform/`으로 이동할 수 있습니다. 그래도 Project
Auth realm/client 구성은 `gitops/apps/systems/auth-system/`에 남습니다.
현재 Keycloak과 PostgreSQL은 Project Auth 전용이므로 모두 system
소유입니다.

## Path contract

환경 중립 base와 cluster-specific overlay를 분리하는 것이 목표
contract입니다.

```text
gitops/platform/shared-services/<name>/base
gitops/apps/systems/<system>/base
gitops/apps/workloads/<workload>/base

gitops/clusters/<cluster>/overlays/platform/<name>
gitops/clusters/<cluster>/overlays/systems/<system>
gitops/clusters/<cluster>/overlays/workloads/<workload>

gitops/platform/control-plane/argocd/projects
gitops/platform/control-plane/argocd/application-sets
```

Base에는 재사용 가능한 workload 구조, Service, ServiceAccount와 기본
configuration contract를 둡니다. Overlay에는 다음처럼 클러스터와 환경을
알아야 하는 값을 둡니다.

- namespace와 public/internal host
- image reference; 정상 promotion의 목표는 immutable digest
- Vault auth role과 KV path annotation
- NetworkPolicy의 namespace/CIDR
- dev-only resource profile와 TLS 차이

Argo CD는 base를 직접 source로 사용하지 않고 반드시 최종 overlay를
reconcile합니다.

현재 first-party overlay의 짧은 commit tag는 이관 예외입니다. Registry를
검증할 credential 없이 임의 digest로 바꾸지 않고 다음 정상 promotion
PR에서 immutable digest로 전환합니다.

### 현재 base의 알려진 예외

Base 내부의 PostgreSQL·Keycloak 참조는 namespace를 포함하지 않은 짧은
Service DNS를 사용하므로 overlay namespace에 재사용할 수 있습니다. 다만
아직 다음 dev/single-node 가정은 남아 있습니다.

- `gitops/apps/systems/auth-system/base`의 Keycloak 실행 command가
  `start-dev`입니다.
- `gitops/platform/shared-services/vault/base/files/vault/vault.hcl`이
  `tls_disable = 1`과 고정된 single-node `node_id`를 사용합니다.

이는 숨겨진 환경 중립성이 아니라 명시적인 리팩터링 부채입니다. 두 번째
환경이나 replica를 만들기 전에 dev 전용 command, TLS와 node identity를
overlay 또는 입력 가능한 configuration으로 옮깁니다.

```text
base -> dev-k3s overlay -> ApplicationSet inventory -> generated Application
     -> Argo CD -> Kubernetes
```

## Platform 안의 두 역할

`platform` ownership에는 다음 두 종류가 있습니다.

- Cluster addon: Kubernetes API를 확장하거나 admission/control-plane
  기능을 제공하는 외부 chart. 현재 Sealed Secrets와 Vault Agent Injector가
  해당합니다. Inventory는
  `gitops/platform/control-plane/argocd/application-sets/platform-addons.yaml`에
  둡니다.
- Shared service: 일반 workload처럼 namespace에서 실행되지만 여러 system이
  사용할 수 있는 capability. 현재 Vault가 해당합니다.

외부 Helm chart를 복사해 base처럼 유지하지 않습니다. chart version과
values는 Argo inventory에서 pin합니다. 저장소가 직접 소유하는 shared
service manifest만 `gitops/platform/shared-services/`에 둡니다.

`foundation`은 소유권 분류가 아닙니다. Bootstrap 때 먼저 필요하다는 뜻은
분리된 ApplicationSet category, `autoSync` gate와 runbook 순서로
표현합니다. 따라서 새로운 `foundation/` business directory를 만들지
않습니다.

## System와 workload의 경계

`gitops/apps/systems/auth-system`은 인증 bounded context가 함께 책임지는
데이터와 identity backing services입니다.

- PostgreSQL StatefulSet와 초기 database contract
- Keycloak server와 Project Auth realm
- Keycloak client synchronization

`gitops/apps/workloads/auth-server`와 `gitops/apps/workloads/api-server`는
각각 별도 source repository와 release digest가 있는 애플리케이션입니다.
Workload가 auth-system을 사용하더라도 두 lifecycle을 합치지 않습니다.

Dev namespace도 소유권을 드러냅니다.

| 소유 단위 | Namespace |
|---|---|
| Vault shared service와 injector | `vault` |
| Project Auth backing system | `auth-system-dev` |
| Auth workload | `auth-dev` |
| API workload | `api-dev` |

## Vault path grammar

KV path도 같은 소유권 언어를 사용합니다.

```text
kv/dev/systems/auth-system/postgres/superuser
kv/dev/systems/auth-system/postgres/auth-server
kv/dev/systems/auth-system/postgres/keycloak
kv/dev/systems/auth-system/keycloak/bootstrap-admin
kv/dev/workloads/auth-server/keycloak-client
```

Vault policy 파일에는 KV-v2 API path인 `kv/data/...`를 사용하고, CLI에는
mount-relative path인 `kv/dev/...`를 사용합니다. 이전
`kv/dev/platform/...` 경로는 legacy migration source일 뿐 새 desired
state가 아닙니다.

## 새 항목 배치 예

| 변경 | 위치 |
|---|---|
| 또 다른 공용 admission controller | `gitops/platform/control-plane/argocd/application-sets/platform-addons.yaml` |
| 공용 object storage service base | `gitops/platform/shared-services/object-storage/base` |
| Project Auth 전용 Redis | `gitops/apps/systems/auth-system/base` |
| 새 first-party worker | `gitops/apps/workloads/<worker>/base` |
| dev worker digest/secret annotation | `gitops/clusters/dev-k3s/overlays/workloads/<worker>` |
| Vault workload policy/role | `infrastructure/live/dev-k3s/vault-workloads`와 그 아래 `policies/` |
| Vault auth backend | `vault-foundation` Terraform state |

분류가 애매하면 설치 순서가 아니라 owner와 소비자 경계를 ADR에 먼저
기록합니다.