# Pysae Projects Reference

Cross-cutting **infrastructure** reference (ArgoCD topology, Datadog tags, EKS, deploy
naming, build conventions, operational notes) — the parts that are **not** per-repo config.

> **Per-repo config lives in `.pysae-ai-tools.yaml`, not here.** For a repo's identity,
> Slack routing, deploy topology (k8s/ECR/Datadog services), AWS resources (S3/ECR/
> ElastiCache/secrets), Prefect topology, release/board flags — and the meaning of every
> config field — use the **`/project-configuration`** skill (one repo, the current repo, or
> all). It wraps `pysae-ai-tools project show` / `project list` and documents the schema.
>
> Dynamic branch context (MR, ticket, epic, CI, branch) is a separate concern:
> `pysae-ai-tools internal detect-context` (always live, never cached).

## Projects

To resolve the GitLab project ID for API calls on a repo: `glab api "projects/pysae%2F<repo>/..."`
(URL-encode the path). For subgroup repos: `pysae%2Fshift%2Fapp`. Note `pysae/platform-tools`
is the old name of **`pysae/tools/ai-tools`** (same repo). The list of repos + their identity
is config-derived — see `/project-configuration all`.

## Kubernetes — deploy naming conventions

Per-repo services (k8s deployment, ECR image, Datadog service) are config (`k8s.services`,
via `/project-configuration`). The **naming convention** itself:

- A service's deployment name = its templated `deployment` resolved for the env:
  `<env>-<service>` → `dev-api-fast`, `prod-api-ndp`, `review-<slug>-op`.
- Namespaces: `dev` / `prod` / `mr` (review). Review environments deploy all apps together
  under namespace `mr`; the orchestrator app is `review-<slug>-main`.
- The API runs as multiple **flavors** (api-fast, api-ndp, …) all sharing the single
  `apps/api` image (no per-flavor image).
- Infra apps (cert-manager, ingress…) deploy under their own fixed per-app namespace.

### Container registry — image tag formats

All app images live in AWS ECR: `596368530845.dkr.ecr.eu-west-3.amazonaws.com/<image>:<tag>`
(the image list is config — `aws.ecr`). Tag formats (CI build convention):

- Dev: `main-<short-sha>` (or `main-<short-sha>-dev` for driver/info)
- Prod: `v<major>-<minor>-<patch>-<short-sha>` (semver)
- Review: `<branch-slug>-<short-sha>`

## ArgoCD — root apps (App-of-Apps)

Per-repo ArgoCD apps are config (`k8s.services`). The cluster-level **root apps** are not:

| App            | Cluster | Source repo                |
|----------------|---------|----------------------------|
| `apps-root`    | both    | `pysae/argo-apps`          |
| `infra-root`   | both    | `pysae/infra/argo-infra`   |
| `dev-main`     | dev     | `pysae/argo-apps`          |
| `prod-main`    | prod    | `pysae/argo-apps`          |

Prefect workers deploy from the Helm chart `prefecthq.github.io/prefect-helm` (ArgoCD apps
`dev-prefect-worker` / `prod-prefect-worker`); the repo's service config is in `pysae/prefect`.

## Datadog

### Environment tags (`env`)

| Value | Description |
|-------|-------------|
| `prod` | Production |
| `dev` | Development (main branch deployed) |
| `review-<slug>` | Review environment (one per MR, slug = branch name) |
| `local` | Local development |
| `global` | Cross-environment (used for finops/cost monitors) |

### Service tags (`service`)

Each service's Datadog `service` tag is config (`k8s.services[].datadog_service`, via
`/project-configuration`). One non-k8s case: **`redis`** is not a k8s service — it is **AWS
ElastiCache** declared in `pysae/infra/infra-cluster` (a shared cache + a dedicated Kong
rate-limit Redis), exposed in config as `aws.elasticache`; query it directly in Datadog by
`service:redis`.

Monitors are tagged with `env` and `service`. Finops monitors use `team:finops` and `type:budget`.

## AWS

Account: `596368530845` | Region: `eu-west-3` (Paris). S3 buckets, ECR images, ElastiCache
clusters and SecretsManager stores are config (`aws.*`, via `/project-configuration`) — the
infra repos that own them are `pysae/infra/infra-common` and `pysae/infra/infra-cluster`.

### EKS Clusters

| Cluster | Purpose |
|---------|---------|
| `dev` | Development + review environments |
| `prod` | Production |
| `pysae-perf` | Performance/load testing |

### Secret values

Config only ever carries secret/key/store **names** (`k8s.secrets`, `aws.secrets`). The
actual key catalogue and values are in AWS Secrets Manager — list a bundle's keys (names
only) with `pysae-ai-tools secrets read --secret-id pysae/<env>/secrets` (no key = list keys;
never print values).

## Operational

### Dev environment wake-up / sleep

The dev environment has a cost-saving mechanism:
- **Sleep**: scales down dev deployments to 0 replicas (nightly or manual)
- **Wake-up**: scales back up (morning or manual trigger via CI job in `infra-cluster`)

### Cross-repo deploy dependencies

Some changes ripple across repos: an `pysae/api` OpenAPI change drives op's Orval codegen
(`op`, `driver`, `info` are API consumers); `pysae/gtfsrt-to-siri` feeds op's SIRI config UI.
Infra-level dependencies: changes to `pysae/infra/gitlab-templates` (CI templates) may
require all repos, and `pysae/argo-apps` values changes sync the target service via ArgoCD.
