Architecture Decision Records (ADRs) for Hop3¶

Architectural Decision Records (or ADR) are documents that capture important architectural decisions made along with their context and consequences.

This process is inspired by Python's PEP process and Gel's RFC process.

ADR Index¶

#	Title	Type	Status
001	Config Files for Hop3	Feature	Accepted
002	Detailed `hop3.toml` Format	Feature	Accepted
003	Config Parsing and Validation	Feature	Accepted
004	Development Tooling	Process	Active
005	Web Terminal for Application Management	Feature	Deferred
006	Nix Integration with Hop3	Feature	Accepted
007	Nix Builders for Existing Packages (Nixpkgs Mode)	Feature	Superseded
008	Template-Based Nix Expression Generation	Feature	Final
009	Nix Runtime Integration	Feature	Deferred
010	Security and Resilience (Umbrella)	Feature	Accepted
011	Data Encryption and Protection	Feature	Accepted
012	Multi-Factor Authentication (MFA)	Feature	Deferred
013	Software Supply Chain Security and SBOMs	Feature	Accepted
014	Authentication Bootstrap Process	Feature	Final
015	Documentation and Community Engagement	Process	Active
016	Backup Strategy	Feature	Accepted
017	Distributed, Agent-Based Architecture	Feature	Draft
018	CLI-Server Communication	Feature	Final
019	Basic Commands for the Hop3 Command-Line	Feature	Accepted
020	Pluggable Architecture for Core Deployment Workflow	Feature	Final
021	Proxy Plugin System for Reverse Proxy Configuration	Feature	Final
022	Build and Deployment Plugin System	Feature	Final
023	Runtime Stack Replacement	Feature	Draft
024	Backup and Restore System	Feature	Final
025	CLI User Experience Improvements	Feature	Final
026	Dashboard UI Test Classification	Guideline	Superseded
027	Configuration System Refactoring for Testability	Feature	Final
028	Pluggy + Dishka Integration for Plugin-Contributed Services	Feature	Final
029	Application Reconciliation and Health Check System	Feature	Accepted
030	Two-Level Build Architecture	Feature	Final
031	Project Terminology (Ubiquitous Language)	Guideline	Active
032	Deployment Strategies and Artifact Lifecycle	Feature	Accepted
033	Docker Integration Strategy	Feature	Final
034	Streaming Deployment Logs	Feature	Final
035	Build Artifacts as Runtime Contract	Architecture	Final
036	CLI Ergonomics and Command Surface	Design	Accepted
037	Git-Based Deployment Architecture	Architecture	Final
038	Multi-Service Application Support	Feature	Accepted
039	Python Deploy Strategies — Clarify and Make Explicit	Feature	Accepted
040	Network firewall and per-app port exposure	Feature	Superseded
041	Privileged Operations Agent (hop3-rootd)	Architecture	Accepted
042	CLI Context Model — Servers and Project Contexts	Feature	Accepted
043	Unified Testing Architecture	Process	Accepted
044	Nightly Test Lab — a Web App to Run and Report on the Full Test Suite	Architecture	Draft
045	Fixed-Port Registry — Exclusive Host Ports for Non-HTTP Apps	Architecture	Accepted
046	Declarative Application Resources — Generated Secrets, Persistent Volumes, Dynamic Env, and Resource Limits	Feature	Accepted
047	CLI Invocation Context — transmit the resolved app and environment with every call	Feature	Draft
048	Server Configuration and Secret Storage	Architecture	Accepted
049	Catalog Distribution — Fetching App Specs from a Central Source	Feature	Accepted
050	Layer-7 Web Application Firewall (LeWAF)	Feature	Accepted

ADRs by Status¶

Accepted (22)¶

Final (15)¶

Active (3)¶

Draft (4)¶

Deferred (3)¶

Superseded (3)¶

ADR Types¶

An ADR can describe one of three types:

Type	Description	Final Status
Feature	New functionality or capability in Hop3	Final
Architecture	Cross-cutting structural decisions (build, deploy, agents)	Implemented / Accepted
Design	Interface/UX and command-surface decisions	Accepted
Process	How we do things (workflows, development practices)	Active
Guideline	Conventions, best practices, standards	Active

ADR Statuses¶

Lifecycle¶

                    ┌─────────────┐
                    │    Draft    │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Accepted │ │ Rejected │ │ Deferred │
        └────┬─────┘ └──────────┘ └──────────┘
             │
      ┌──────┴──────┐
      ▼             ▼
┌──────────┐  ┌──────────┐
│  Final   │  │  Active  │
│(features)│  │(process/ │
└──────────┘  │guideline)│
              └────┬─────┘
                   ▼
             ┌──────────┐
             │ Inactive │
             └──────────┘

Status Definitions¶

Status	Description
Draft	Initial proposal, not yet reviewed or discussed
Accepted	Approved after discussion, ready for implementation
Rejected	Explicitly decided against after discussion
Deferred	Parked for later consideration (not rejected, just not now)
Final	Feature is fully implemented (note which version)
Active	Process or guideline is in effect
Inactive	Process or guideline has been abandoned or replaced
Superseded	Replaced by a newer ADR (reference the replacement)

ADR Structure¶

Required Preamble¶

Every ADR should start with a structured metadata block:

# ADR NNN: Title

**Status**: Draft | Accepted | Rejected | Deferred | Final | Active | Inactive | Superseded
**Type**: Feature | Process | Guideline
**Created**: YYYY-MM-DD
**Authors**: Name <email> (optional)
**Implemented-In**: vX.Y.Z (for Final status)
**Superseded-By**: ADR NNN (if superseded)
**Related-ADRs**: NNN, NNN, NNN

Required Sections¶

Context - What is the issue motivating this decision?
Decision - What change are we proposing?
Consequences - What are the positive and negative outcomes?

Recommended Sections¶

Motivation - Why is the existing situation inadequate?
Detailed Design - Technical specification
Examples - Practical scenarios demonstrating the decision
Alternatives Considered - Other options and why they were rejected
Security Implications - Security considerations
Backwards Compatibility - Impact on existing functionality

ADR Guidelines¶

ADRs should provide:

Decision-focused content - Why we made these choices
Complete interfaces - Anyone can implement against the design
Concrete examples - Not abstract, but simplified
Configuration guidance - How to use and configure
Trade-offs documentation - Alternatives considered and why rejected

ADRs should NOT include:

Exhaustive feature lists for each implementation
Step-by-step integration guides
Implementation details for all variants
Detailed testing procedures

The ADRs are architectural specifications with sufficient detail to understand responsibilities and implement functionalities, while remaining focused on decisions rather than becoming implementation manuals.

Full Template¶

# ADR NNN: Title

**Status**: Draft
**Type**: Feature
**Created**: YYYY-MM-DD
**Authors**: Name <email>
**Related-ADRs**: NNN, NNN

## Context

What is the issue that we're seeing that is motivating this decision or change?

- Current situation (as-is state)
- Pain points or limitations
- Stakeholders affected

## Motivation

Why is the existing situation inadequate to address the problem?

- Why now? What triggered this decision?
- What happens if we do nothing?

## Decision

What is the change that we're proposing and/or doing?

- High-level summary of the approach
- Key principles or tenets guiding this decision

## Detailed Design

Explain the design in enough detail for someone familiar with the ecosystem
to understand and implement.

- Architecture and components
- Interfaces and protocols
- Configuration options
- Corner cases and edge conditions

## Examples

Illustrate the detailed design with examples.

- Common use cases
- Configuration examples
- API usage examples

## Consequences

### Positive

- Benefits and improvements
- Problems solved

### Negative

- Trade-offs and limitations
- New complexity introduced
- Migration or compatibility concerns

## Security Implications

Security considerations for this decision.

- Authentication/authorization impact
- Data protection concerns
- Attack surface changes

## Backwards Compatibility

Impact on existing functionality.

- Breaking changes
- Migration path
- Deprecation timeline

## Alternatives Considered

What other options did we consider? Why were they rejected?

- Alternative A: Description, pros, cons, why rejected
- Alternative B: Description, pros, cons, why rejected

## Prior Art

How do other projects solve this problem?

- Similar solutions in other systems
- Lessons learned from previous attempts

## Unresolved Questions

What parts of the design are still TBD?

- Open issues to be resolved during implementation
- Questions needing further research

## Future Work

What future work is implied by this decision?

- Follow-up ADRs needed
- Features enabled by this decision
- Technical debt to address later

## References

- Links to relevant documentation, issues, or discussions
- External specifications or standards

Minimal Template¶

For smaller decisions, a minimal template may suffice:

# ADR NNN: Title

**Status**: Draft
**Type**: Feature
**Created**: YYYY-MM-DD
**Authors**: Name <email>

## Context

[Brief description of the problem]

## Decision

[What we decided to do]

## Consequences

[Key positive and negative outcomes]