devops-lib-gcp/docs/adr/README.md

Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for devops-lib. These were retroactively documented on 2026-05-12 through codebase analysis and developer interviews.

What is an ADR?

An Architecture Decision Record captures an important architectural decision along with its context, alternatives, and consequences. They help new team members understand WHY the system is built the way it is — not just what it does.

Decisions

#	Decision	Category	Status	Assessment
0001	Single shared library consumed by all services	PATTERN	Accepted	Still appropriate
0002	Branch name as sole environment selector	PATTERN	Accepted	Still appropriate
0003	Policy exceptions in separate Meesho/whitelists repo	PATTERN	Accepted	Still appropriate
0004	Whitelist cloned fresh on every build — no caching	PATTERN	Accepted	Still appropriate
0005	Config-only change detection — skip build, reuse latest image	PATTERN	Accepted	Still appropriate
0006	Ringmaster as mandatory build trigger gate	PATTERN	Accepted	Still appropriate
0007	GitOps via strict 4-step ArgoCD sync sequence	INFRA	Accepted	Still appropriate
0008	Canary deploy mandatory for Tier-1 (sp0/up0) services in prd	RELIABILITY	Accepted	Still appropriate
0009	JVM heap auto-derived from pod memory_request	RELIABILITY	Accepted	Still appropriate
0010	Cloud-and-branch namespaced artifact paths	DATA	Accepted	Adequate with caveats
0011	Build-user identity routes post-build callbacks	COMMUNICATION	Accepted	Adequate with caveats
0012	String-interpolated Helm values from user config.yaml	COMMUNICATION	Accepted	Adequate with caveats
0013	Multi-zone deployables gated out of direct Jenkins ArgoCD	RELIABILITY	Accepted	Still appropriate
0014	Open Dependabot CRITICAL alerts block builds	RELIABILITY	Accepted	Still appropriate
0015	Node install logic paired across buildNode.groovy and Dockerfile	PATTERN	Accepted	Still appropriate
0016	Per-environment Helm chart versioning (values_v2 vs values_v3)	INFRA	Accepted	Adequate with caveats

How to use

• New to the project? Read these to understand why things are the way they are before touching the code.
• Making a change? Check if an existing ADR covers the area you're modifying — especially ADR-0003 (whitelists), ADR-0004 (whitelist caching), ADR-0007 (ArgoCD sequence order), ADR-0013 (multi-zone gating), ADR-0014 (Dependabot CRITICAL gate).
• Making a new architectural decision? Create a new ADR using the template in an existing file as a guide.

Adding a new ADR

1. Copy an existing ADR as a template
2. Use the next sequential number (currently: 0017)
3. Fill in all sections — if you don't have info for a section, say so rather than leaving it blank
4. Get a review from the DevOps Platform team lead
5. Add a row to the table above