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	Status
001	Three-Branch Strategy	Critical	Accepted
002	GitHub Actions Automation	Critical	Accepted
003	Template Repository Pattern	Critical	Accepted

Repository Initialization & Setup

"How do I create and configure a new fork?"

Decisions governing repository initialization, configuration, and security setup:

ADR	Decision	Impact	Status
006	Two-Workflow Initialization	High	Accepted
007	Workflow Bootstrap Pattern	Medium	Accepted
008	Centralized Label Management	Medium	Accepted
016	Initialization Security Handling	Medium	Accepted
017	MCP Server Integration	Medium	Accepted

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	Status
005	Conflict Management Strategy	Critical	Accepted
009	Asymmetric Cascade Review	Medium	Accepted
019	Cascade Monitor Pattern	High	Accepted
021	Pull Request Target Pattern	Medium	Accepted
023	Meta Commit Strategy	High	Accepted
024	Duplicate Prevention Architecture	Medium	Accepted

State Management & Tracking

"How do I track progress and workflow state?"

Decisions for managing workflow state and tracking lifecycle:

ADR	Decision	Impact	Status
020	Human-Required Label Strategy	High	Accepted
022	Issue Lifecycle Tracking	Medium	Accepted

Build, Test & Dependencies

"How do I build, test, and maintain dependencies?"

Build architecture, dependency management, and documentation:

ADR	Decision	Impact	Status
025	Java/Maven Build Architecture	High	Accepted
026	Dependabot Security Updates	Medium	Accepted
027	Documentation Generation	Medium	Accepted

Release Management

"How do releases get created and published?"

Version management and release automation:

ADR	Decision	Impact	Status
004	Release Please Versioning	High	Accepted

Template Maintenance & Evolution

"How do fork repositories stay updated with template improvements?"

Decisions for propagating template updates to fork repositories:

ADR	Decision	Impact	Status
011	Configuration-Driven Sync	High	Accepted
012	Template Update Propagation	High	Accepted
018	Fork-Resources Staging	Medium	Accepted

Workflow Infrastructure & Patterns

"What are the reusable building blocks?"

Technical patterns and infrastructure for workflow implementation:

ADR	Decision	Impact	Status
010	YAML-Safe Shell Scripting	Medium	Accepted
013	Reusable GitHub Actions	Medium	Accepted
014	AI-Enhanced Workflows	High	Accepted
015	Template-Workflows Separation	Medium	Accepted
028	Workflow Script Extraction	Medium	Accepted
029	GitHub App Authentication	High	Accepted

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.