Chris Farhood
7443187c4f
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>
49 lines
1.6 KiB
Markdown
49 lines
1.6 KiB
Markdown
# 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](001-result-types.md) | Result Types for Error Handling | Accepted | 2026-02-11 |
|
|
| [002](002-branded-types.md) | Branded Types for Type Safety | Accepted | 2026-02-11 |
|
|
| [003](003-client-side-crypto.md) | Client-Side Encryption | Accepted | 2026-02-11 |
|
|
| [004](004-rbac-integration.md) | RBAC-Aware UI | Accepted | 2026-02-11 |
|
|
| [005](005-react-hooks-extraction.md) | Custom React Hooks | Accepted | 2026-02-12 |
|
|
|
|
## Creating New ADRs
|
|
|
|
When making significant architectural decisions:
|
|
|
|
1. Copy template:
|
|
```bash
|
|
cp docs/architecture/adr/template.md docs/architecture/adr/NNN-title.md
|
|
```
|
|
|
|
2. Fill in the template
|
|
|
|
3. Update this index
|
|
|
|
4. Link from relevant documentation
|
|
|
|
## References
|
|
|
|
- [ADR GitHub Organization](https://adr.github.io/)
|
|
- [Michael Nygard's ADR Template](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
|