Architecture Principles

These principles guide design and tradeoff decisions across infrastructure and applications.

Principle 1: Git is the source of truth

Runtime configuration and infrastructure are declared in code and reconciled through GitOps.

Principle 2: Contracts over assumptions

Every shared capability must expose an explicit contract:

• What platform provides
• What applications must implement
• How to verify it works

Principle 3: Secure by default

• No long-lived static credentials in repositories
• Workload Identity for pod and CI authentication
• Principle of least privilege for GCP IAM bindings

Principle 4: Observable by default

• Structured logs
• Correlatable traces
• Actionable metrics and alerts

Principle 5: Documentation is a product

Documentation should be discoverable, versioned, and easy to navigate for both:

• engineers with deep infrastructure experience
• engineers without devops background