Architecture Decision Records
This catalog documents the architectural choices that shape the OSDU SPI Fork Management system. Each ADR captures the context, rationale, and consequences of significant design choices that enable automated management of long-lived upstream forks.
Impact Levels
Critical - Fundamental to system operation; changes require careful migration planning
High - Significant workflow effects; changes affect multiple components
Medium - Localized improvements; changes have bounded effects
Catalog
Foundation & Core Architecture
"What are the fundamental design choices?"
Foundation decisions that define the system's structure and approach:
| ADR | Decision | Impact |
|---|---|---|
| 001 | Three-Branch Strategy | Critical |
| 002 | GitHub Actions Automation | Critical |
| 003 | Template Repository Pattern | Critical |
Repository Initialization & Setup
"How do I create and configure a new fork?"
Decisions governing repository initialization, configuration, and security setup:
| ADR | Decision | Impact |
|---|---|---|
| 006 | Two-Workflow Initialization | High |
| 007 | Workflow Bootstrap Pattern | Medium |
| 008 | Centralized Label Management | Medium |
| 016 | Initialization Security Handling | Medium |
| 017 | MCP Server Integration | Medium |
Upstream Synchronization & Integration
"How do I keep my fork in sync with upstream?"
Decisions for synchronizing with upstream repositories and integrating changes:
| ADR | Decision | Impact |
|---|---|---|
| 005 | Conflict Management Strategy | Critical |
| 009 | Asymmetric Cascade Review | Medium |
| 019 | Cascade Monitor Pattern | High |
| 021 | Pull Request Target Pattern | Medium |
| 023 | Meta Commit Strategy | High |
| 024 | Duplicate Prevention Architecture | Medium |
State Management & Tracking
"How do I track progress and workflow state?"
Decisions for managing workflow state and tracking lifecycle:
| ADR | Decision | Impact |
|---|---|---|
| 020 | Human-Required Label Strategy | High |
| 022 | Issue Lifecycle Tracking | Medium |
Build, Test & Dependencies
"How do I build, test, and maintain dependencies?"
Build architecture, dependency management, and documentation:
| ADR | Decision | Impact |
|---|---|---|
| 025 | Java/Maven Build Architecture | High |
| 026 | Dependabot Security Updates | Medium |
| 027 | Documentation Generation | Medium |
CI/CD & Deployment
"How do services get built, deployed, and tested per PR?"
Decisions for the container-image build, cluster deploy, and integration-test pipeline:
| ADR | Decision | Impact |
|---|---|---|
| 033 | GHCR as Service Image Registry | Medium |
| 035 | Azure-Only Maven Profile Restriction | Medium |
| 036 | Workflow Trust Boundaries for CI/CD | High |
| 037 | Engineering System Owns the Canonical Service Dockerfile | High |
Release Management
"How do releases get created and published?"
Version management and release automation:
| ADR | Decision | Impact |
|---|---|---|
| 004 | Release Please Versioning | High |
Template Maintenance & Evolution
"How do fork repositories stay updated with template improvements?"
Decisions for propagating template updates to fork repositories:
| ADR | Decision | Impact |
|---|---|---|
| 011 | Configuration-Driven Sync | High |
| 012 | Template Update Propagation | High |
| 018 | Fork-Resources Staging | Medium |
| 031 | Template Sync Duplicate Prevention | Medium |
Workflow Infrastructure & Patterns
"What are the reusable building blocks?"
Technical patterns and infrastructure for workflow implementation:
| ADR | Decision | Impact |
|---|---|---|
| 010 | YAML-Safe Shell Scripting | Medium |
| 013 | Reusable GitHub Actions | Medium |
| 014 | AI-Enhanced Workflows | High |
| 015 | Template-Workflows Separation | Medium |
| 028 | Workflow Script Extraction | Medium |
| 029 | GitHub App Authentication | High |
| 030 | CodeQL Summary Job Pattern | High |
Navigation Tips
Finding Relevant ADRs
By Workflow Task: Use the question-based categories above to find ADRs related to specific activities (initialization, synchronization, build, release, etc.).
By Impact Level: Focus on Critical and High Impact ADRs when understanding core system behavior or planning significant changes.
By Category: Navigate to specific sections when troubleshooting issues in particular workflow areas.
Understanding Context
Most ADRs reference related decisions. Follow the cross-reference links to understand how decisions build upon each other and why certain patterns evolved.
For insights on lessons learned and architectural principles, see Learnings.