Skip to content

Explanation

Explanation documentation is understanding-oriented. It clarifies concepts, provides background, and helps you understand why things work the way they do.

What You'll Find Here

Explanation content in Fawkes is designed to:

  • Provide context and background knowledge
  • Explain concepts, architecture decisions, and design choices
  • Help you understand the "why" behind features
  • Connect different parts of the platform together

Core Concepts

The following explanatory content provides deep-dive understanding of Fawkes architectural decisions and design philosophy.

Architecture & GitOps

Topic Description
GitOps Strategy Why ArgoCD, the App-of-Apps pattern, and the shift from push to pull deployment
GitOps Principles Declarative, version-controlled infrastructure - See Module 3: GitOps Principles
Loosely Coupled Architecture Why independence matters - See Architecture

Containers & Build Strategy

Topic Description
Buildpacks Philosophy The trade-offs of Cloud Native Buildpacks vs. Dockerfiles for security and maintenance

Security & Compliance

Topic Description
Zero Trust Model How Vault, Kyverno, and Istio/Ingress work together for defense in depth
Policy as Code Tiers Understanding the Audit vs. Enforce governance model
Shift Left Security Why early security testing matters - See Module 7: Security Scanning
Zero Trust Architecture Modern security principles - See Module 19: Security Zero Trust

Observability

Topic Description
Unified Telemetry The role of OpenTelemetry as the standard vs. vendor-specific agents

Platform Engineering

Topic Description
Product Discovery & Delivery Flow (IP3dP) How to treat your platform as a product with continuous discovery and measurement
What is an Internal Developer Platform? Understanding IDPs and their value - See Module 1: What is IDP
Platform as a Product Operating your platform with product thinking - See ADR-020
Golden Paths Paved roads for developer productivity - See Golden Path Usage

DORA & Performance

Topic Description
Understanding DORA Metrics The four key metrics and why they matter - See Module 2: DORA Metrics
Elite Performance What it means to be an elite performer - See Home page

Business Value

Topic Description Status
ROI of Platform Engineering Quantifying platform value See Business Case
Developer Experience Why DX matters for business outcomes See DX Metrics ADR
Risk Mitigation How platforms reduce organizational risk 🚧 Coming soon

How This Differs from Other Documentation

Explanation How-To Guides Reference
Discusses concepts Shows steps Lists specifications
Provides background Solves problems Provides data
Explains decisions Gives instructions Documents APIs
Connects ideas Focuses on tasks Describes options

Architectural Decision Records

For detailed rationale behind specific decisions, see our ADR collection.

View ADRs Explore Patterns