Enhancement: Add Architecture Decision Records (ADRs)

[sfloess]

Overview

Document key architectural decisions to help future contributors understand why the codebase is structured the way it is.

Current State

• CLAUDE.md documents architecture
• README explains features
• No formal ADR documentation

What Are ADRs?

Architecture Decision Records capture important design decisions with context, consequences, and alternatives considered.

Recommended ADRs

Create docs/adr/ directory with these initial records:

ADR-0001: Why No Spring Boot

• Context: Originally Spring Boot, refactored to plain Java
• Decision: Remove Spring Boot, use minimal dependencies
• Consequence: 50MB → 2.7MB JAR, 3-5s → <200ms startup

ADR-0002: Multi-Platform Architecture via Interfaces

• Context: Need to support Desktop, Android, iOS with shared logic
• Decision: NexusHttpClient and Credentials interfaces
• Alternatives: Code duplication, platform-specific repos

ADR-0003: OkHttp for Android vs java.net.http for Desktop

• Context: Android doesn't support java.net.http
• Decision: Interface-based HTTP client abstraction
• Consequence: Platform-optimized implementations

ADR-0004: Password Encryption in Properties Files

• Context: Security concern with plaintext passwords
• Decision: Use jencrypt (AES-256-GCM) for credential storage
• Alternatives: External secret managers, environment variables only

ADR-0005: Seven Distinct User Interfaces

• Context: Different users have different preferences
• Decision: CLI, Swing, AWT, Terminal UI, Android, iOS, macOS
• Consequence: Maintenance burden, but excellent UX flexibility

ADR-0006: X.Y.Z Semantic Versioning Adoption

• Context: Auto-incrementing X.Y was confusing
• Decision: Switch to semver (X.Y.Z) for all modules
• Reference: Issue Versioning: Inconsistent version numbering across modules causes confusion #46

Template

# ADR-XXXX: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-YYYY]

## Context
What is the issue we're seeing that is motivating this decision?

## Decision
What is the change we're proposing/making?

## Consequences
What becomes easier or harder to do because of this change?

## Alternatives Considered
What other options were evaluated?

Benefits

• Onboard new contributors faster
• Prevent re-litigating old decisions
• Document trade-offs for future reference
• Improve architectural transparency

Format

Use MADR (Markdown ADR format)

Priority

Low - Documentation enhancement, not blocking

Related

• CLAUDE.md already captures some of this
• Could migrate CLAUDE.md content to ADRs