privilegedescalation/headlamp-sealed-secrets-plugin

Files

T

Chris Farhood 7443187c4f docs: implement Phase 4 - troubleshooting guides and ADRs

Created comprehensive troubleshooting documentation:
- docs/troubleshooting/README.md - Main troubleshooting hub
- docs/troubleshooting/common-errors.md - Frequent errors and fixes
- docs/troubleshooting/controller-issues.md - Controller problems
- docs/troubleshooting/encryption-failures.md - Encryption debugging
- docs/troubleshooting/permission-errors.md - RBAC troubleshooting

Created Architecture Decision Records:
- docs/architecture/adr/README.md - ADR index
- docs/architecture/adr/001-result-types.md - Result<T,E> pattern
- docs/architecture/adr/002-branded-types.md - Compile-time type safety
- docs/architecture/adr/003-client-side-crypto.md - Browser encryption
- docs/architecture/adr/004-rbac-integration.md - Permission-aware UI
- docs/architecture/adr/005-react-hooks-extraction.md - Custom hooks

Total: 11 files, 2,847 lines added

Troubleshooting guides cover:
- Plugin installation/loading issues
- Controller deployment/connectivity problems
- Encryption/certificate errors
- RBAC permission diagnosis and fixes
- Browser-specific issues
- Network troubleshooting
- Diagnostic commands and tools

ADRs document key architectural decisions:
- Why Result types for error handling (vs exceptions)
- Why branded types for type safety (vs classes)
- Why client-side encryption (vs server-side)
- Why RBAC-aware UI (vs showing all actions)
- Why custom React hooks (vs inline logic)

Each ADR includes:
- Context and problem statement
- Decision and implementation
- Consequences (positive/negative)
- Alternatives considered with rationale
- Real-world impact and examples

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

2026-02-11 23:42:52 -05:00

1.6 KiB

Raw Blame History

Architecture Decision Records (ADRs)

This directory contains Architecture Decision Records for the Headlamp Sealed Secrets plugin.

What is an ADR?

An Architecture Decision Record captures an important architectural decision made along with its context and consequences.

Format

Each ADR follows this structure:

Title: Short descriptive name
Status: Accepted | Superseded | Deprecated
Context: What is the issue we're seeing that is motivating this decision?
Decision: What is the change we're actually proposing/doing?
Consequences: What becomes easier or harder as a result?
Alternatives Considered: What other options did we evaluate?

Index

ADR	Title	Status	Date
001	Result Types for Error Handling	Accepted	2026-02-11
002	Branded Types for Type Safety	Accepted	2026-02-11
003	Client-Side Encryption	Accepted	2026-02-11
004	RBAC-Aware UI	Accepted	2026-02-11
005	Custom React Hooks	Accepted	2026-02-12

Creating New ADRs

When making significant architectural decisions:

Copy template:

cp docs/architecture/adr/template.md docs/architecture/adr/NNN-title.md

Fill in the template
Update this index
Link from relevant documentation

1.6 KiB Raw Blame History