Architecture Decision Records
This section documents significant architectural decisions made during Headjack's development. Each ADR captures the context, decision, and consequences of a particular choice.
What is an ADR?
An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences. ADRs help future contributors understand why certain decisions were made.
Current Decisions
| ADR | Title | Status |
|---|---|---|
| ADR-001 | macOS-Only Platform Support | Accepted |
| ADR-002 | Apple Containerization Framework | Accepted |
| ADR-003 | Go as Implementation Language | Accepted |
| ADR-004 | CLI-Based Agents over API-Based | Accepted |
| ADR-005 | Defer GPG Commit Signing Support | Accepted |
| ADR-006 | OCI Images for Environment Customization | Accepted |
Key Themes
These decisions reflect several key themes in Headjack's design:
- Simplicity over generality: macOS-only, OCI images only, CLI agents only
- Leverage existing ecosystems: Apple Containerization, Go CLI patterns, standard OCI tooling
- Defer complexity: GPG support deferred, Nix support left to users
- Optimize for the common case: Subscription-based agents, opinionated base images