Adr

# Areas to analyze:
1. Platform choices (ESP8266, Arduino, frameworks)
2. Memory management patterns (static buffers, PROGMEM)
3. Network architecture (protocols, security models)
4. Integration patterns (MQTT, APIs, WebSocket)
5. Core system design (timers, scheduling, persistence)
6. Hardware interfaces (sensors, watchdog, GPIO)
7. Build and development tools

For each pattern discovered:
- WHY was this approach chosen? (context, constraints)
- WHAT alternatives exist? (at least 2-3 viable options)
- WHY were alternatives rejected? (specific technical reasons)
- WHAT are the consequences? (benefits, costs, risks)
- HOW is this implemented? (code examples, key files)
- WHEN was this decided? (estimate if unknown)

For each undocumented architectural decision:
1. Use the explore agent to understand the pattern
2. Review code, comments, git history for context
3. Identify constraints (memory, performance, compatibility)
4. Research alternatives (even if obvious)
5. Document consequences (positive AND negative)
6. Create ADR with Status: Accepted (since implemented)
7. Link to actual implementation (files, commits)

Start with foundational decisions that:
- Affect multiple components
- Constrain future choices
- Are non-obvious or counterintuitive
- Have significant trade-offs
- Are frequently questioned

"Analyze this codebase to identify undocumented architectural decisions"
"Generate ADRs for existing architectural patterns in this codebase"
"What architectural decisions should be documented in this project?"

"Identify and document memory management architectural decisions"
"What network architecture decisions are undocumented?"
"Analyze platform choices and create ADRs"

✓ Write for future developers who weren't there
✓ Include code examples and diagrams
✓ Reference related ADRs
✓ Use clear, simple language
✓ Document constraints that drove the decision
✓ Explain consequences (positive and negative)
✓ Link to implementation (files, PRs, commits)
✓ Be critical - question the decision, document risks
✓ Provide specific evidence (measurements, benchmarks)
✓ Explain technical terms on first use

✗ Don't use jargon without explanation
✗ Don't assume reader knows the context
✗ Don't skip alternatives (even obvious ones)
✗ Don't make assumptions unstated
✗ Don't forget to update status when superseding
✗ Don't be vague ("it's better", "improves performance")
✗ Don't skip negative consequences
✗ Don't write marketing copy - be honest about trade-offs

# ADR-XXX: [Concise Decision Title]

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX  
**Date:** YYYY-MM-DD  
**Decision Maker:** [Copilot Agent | User: Name | Team Discussion]

## Context

### Problem Statement
[What problem are we solving? What is the situation or challenge?]

### Background
[Relevant history, current state, or technical context]

### Constraints
[What constraints apply? Hardware, memory, security, compatibility, budget, timeline?]

### Stakeholders
[Who is affected by this decision? Users, developers, operations, integrations?]

## Decision

[Clear statement of the choice made and rationale]

### Why This Choice
[Explain reasoning behind the decision]

### Implementation Summary
[High-level description of how this will be implemented]

## Alternatives Considered

### Alternative 1: [Name]
**Description:** [What is this alternative?]

**Pros:**
- Benefit 1
- Benefit 2

**Cons:**
- Drawback 1
- Drawback 2

**Why Not Chosen:** [Clear explanation]

### Alternative 2: [Name]
[Repeat structure for each alternative]

[Include at least 2-3 alternatives. If none exist, explain why this is the only viable option.]

## Consequences

### Positive
- **[Benefit Category]:** Specific benefit
- **[Another Category]:** Another benefit

### Negative
- **[Cost/Limitation]:** Specific drawback
- **[Trade-off]:** What we're giving up

### Risks & Mitigation
- **Risk:** [Description]  
  **Mitigation:** [How we address this]

### Impact Areas
- **Performance:** [Impact on system performance]
- **Maintainability:** [Impact on code maintenance]
- **Security:** [Security implications]
- **Scalability:** [Scaling implications]
- **Developer Experience:** [Impact on development]

## Implementation Notes

### Key Files/Modules Affected
- `path/to/file.ext` - [Brief description of changes]
- `another/file.ext` - [Brief description]

### Code Examples

```language
// Example showing how this decision is implemented
function example() {
  // Demonstrate the pattern
}

---

## Naming Convention

### ADR File Naming

### Number Assignment

- Sequential numbering starting from 001
- Check `docs/adr/` for highest number and increment
- Don't reuse numbers from deprecated/superseded ADRs
- Don't leave gaps in numbering

---

## ADR Categories

Group ADRs by architectural domain for easier navigation:

- **Platform & Build System** - Platform choice, build tools, frameworks
- **Memory Management** - RAM optimization, buffer strategies, PROGMEM
- **Network & Security** - Protocols, encryption, authentication
- **Integration & Communication** - APIs, MQTT, WebSocket
- **System Architecture** - Core patterns, scheduling, persistence
- **Hardware & Reliability** - Hardware interface, watchdog, sensors
- **Development & Build** - Developer tools, CI/CD, testing
- **Core Services** - Time management, queuing, configuration
- **Features & Extensions** - Specific features, sensor integration
- **Browser & Client** - Frontend, browser compatibility, UX
- **OTA & Updates** - Firmware updates, version management

---

## ADR Workflow

### 1. Before Making Architectural Changes

```bash
# Step 1: Review existing ADRs
- Read docs/adr/README.md for navigation
- Search for related decisions
- Check if change conflicts with existing ADRs
- Understand architectural constraints

# Step 2: Determine if new ADR needed
- Will this have long-term impact?
- Does it affect multiple components?
- Are there multiple alternatives?
- Will future developers need context?

# Step 3: If ADR needed, draft it
- Use the template above
- Fill in all sections thoughtfully
- Include code examples
- Document alternatives thoroughly

# Step 1: Create ADR with Status: Proposed
- Get next ADR number
- Write comprehensive ADR
- Include decision maker (Copilot Agent or User: Name)

# Step 2: Reference ADR in code
- Add comments linking to ADR
- Example: // See ADR-030 for why we use this pattern

# Step 3: Implement according to decision
- Follow patterns established in ADR
- Ensure code aligns with decision
- Implement mitigation for identified risks

# Step 1: Update ADR status to Accepted
- Change Status: Proposed → Accepted
- Add implementation date to timeline
- Link to PR/commit that implemented it

# Step 2: Update docs/adr/README.md
- Add entry to ADR index
- Categorize appropriately
- Update reference counts if applicable

# Step 3: Store memory (if using Copilot)
- Store key facts for future reference
- Include ADR number in citations

# Step 1: Create new ADR
- Write new ADR explaining change
- Reference original ADR
- Explain why change needed

# Step 2: Update old ADR
- Change status to "Superseded by ADR-XXX"
- Do NOT delete or modify decision/context
- Add superseded date to timeline

# Step 3: Update README
- Update both ADRs in index
- Note the supersession relationship

✗ "This change violates ADR-004 (Static Buffer Allocation). 
   The String class should not be used here."

✓ "This change aligns with ADR-007 (Timer-Based Scheduling).
   Good use of DECLARE_TIMER_SEC macro."

? "This introduces a new architectural pattern. 
   Please create an ADR documenting the decision."

! "ADR-029 is referenced but hasn't been updated to Accepted status.
   Please update the status since this is now implemented."

## ADR Compliance Checklist

- [ ] Changes reviewed against existing ADRs
- [ ] No violations of architectural decisions
- [ ] New ADR created if needed (Status: Proposed)
- [ ] ADR status updated if implementing existing ADR
- [ ] Code comments reference relevant ADRs
- [ ] docs/adr/README.md updated if new ADR added

# Check ADR compliance
python evaluate.py  # Includes ADR pattern enforcement

# Verify ADR references are valid
grep -r "ADR-[0-9]" src/ | while read line; do
  # Extract ADR number and verify file exists
  # Report broken references
done

# Check for architectural pattern violations
# (e.g., String usage, missing PROGMEM, etc.)

# .github/workflows/adr-check.yml
name: ADR Compliance Check

on: [pull_request]

jobs:
  adr-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Check ADR compliance
        run: |
          # Run automated checks
          # Verify no ADR violations
          # Check if new ADRs needed
          
      - name: Comment on PR
        if: violations found
        # Post comment suggesting ADR review

# ADR-XXX: [Title]

**Status:** Accepted  
**Date:** YYYY-MM-DD  
**Decision Maker:** User: [Name/Role]  ← IMPORTANT: Mark as human decision

## Context
[User's problem or request]

## Decision
**User Decision:** [What the user chose]

The user explicitly chose [X] over [Y] because [reason given].

## Alternatives Considered
[What was presented to the user]

### Alternative 1: [Option presented]
**User Feedback:** [User's reasoning for/against]

### Alternative 2: [Option presented]
**User Feedback:** [User's reasoning for/against]

## Rationale
**User's Stated Reasons:**
- Reason 1
- Reason 2

**Technical Context:**
[Agent's analysis of the decision's technical implications]

# ADR-030: Use PostgreSQL for Sensor Data Storage

**Status:** Accepted  
**Date:** 2026-02-06  
**Decision Maker:** User: Rob van den Breemen

## Context
User requested evaluation of database options for storing sensor historical data.

## Decision
**User Decision:** Use PostgreSQL instead of SQLite

The user explicitly chose PostgreSQL after being presented with both options,
citing need for multi-client access and superior analytics capabilities.

## Alternatives Considered

### Alternative 1: SQLite
**Pros:** Lightweight, embedded, no server needed  
**Cons:** Single writer limitation  
**User Feedback:** "Need multiple Home Assistant instances to query simultaneously"

### Alternative 2: PostgreSQL
**Pros:** Multi-client, powerful queries, excellent HA integration  
**Cons:** Requires separate server, more complex setup  
**User Feedback:** "Worth the complexity for analytics and flexibility"

## Rationale
**User's Stated Reasons:**
- Need concurrent access from multiple HA instances
- Plan to use TimescaleDB extension for time-series data
- Want to run complex queries for energy analytics
- Already running PostgreSQL for other home automation

**Technical Context:**
This decision means we'll implement a RESTful API for sensor data
instead of direct database access from the firmware.

# When adding new ADR:
1. Add entry under appropriate category
2. Update category count
3. Update "Foundational ADRs" if highly referenced
4. Update "Decision Timeline" if appropriate
5. Add to "Related Decisions" in other ADRs

## Implementation Notes

### WRONG: No example
Use PROGMEM for string literals.

### RIGHT: Clear example
```cpp
// WRONG - String literal wastes RAM
DebugTln("Starting WiFi");

// CORRECT - F() macro stores in flash
DebugTln(F("Starting WiFi"));

// WRONG - strcmp on PROGMEM
strcmp(value, "ON");

// CORRECT - strcmp_P for PROGMEM
strcmp_P(value, PSTR("ON"));

### Include Diagrams When Helpful

```markdown
## Implementation Notes

### Architecture Diagram

### Data Flow

# Review checklist
1. Are any "Proposed" ADRs abandoned? (Mark deprecated)
2. Are any "Accepted" ADRs being violated? (Update enforcement)
3. Do new patterns need ADRs? (Create them)
4. Are superseded ADRs properly linked? (Verify)
5. Is README accurately reflecting current state? (Update)