Chris Farhood
57e1298d12
Implement Phase 1 of documentation standardization plan: **New Documentation Structure:** - docs/README.md - Documentation hub with quick links - docs/getting-started/ - Installation, prerequisites, quick-start - docs/deployment/ - Kubernetes, Helm, production guides - docs/architecture/ - Overview, data-flow, design-decisions, ADR template - docs/troubleshooting/ - Quick diagnosis, common issues, RBAC, network - docs/development/ - Testing guide (moved from docs/TESTING.md) **Granular Breakdown:** - Split DEPLOYMENT.md → installation.md, kubernetes.md, helm.md, production.md - Split ARCHITECTURE.md → overview.md, data-flow.md, design-decisions.md - Split TROUBLESHOOTING.md → README.md, common-issues.md, rbac-issues.md, network-problems.md **New Content:** - Quick Start guide (5-minute setup) - Prerequisites checklist - Production deployment best practices - ADR template and index - Quick diagnosis table **Updated:** - README.md now links to new documentation structure - All documentation cross-referenced with relative links Implements standardization plan from docs/DOCUMENTATION_STANDARDIZATION_PLAN.md 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>
Architecture Decision Records
This directory contains Architecture Decision Records (ADRs) for significant architectural choices made in the Headlamp Polaris Plugin.
What is an ADR?
An Architecture Decision Record (ADR) captures an important architectural decision made along with its context and consequences. AD Rs provide historical context for future developers and serve as documentation for why certain approaches were chosen.
When to Create an ADR
Create an ADR when:
- Making a significant architectural choice (e.g., state management approach)
- Selecting between multiple technology options (e.g., React Context vs. Redux)
- Establishing a pattern that impacts multiple components
- Making a trade-off decision with non-trivial consequences
- Introducing a new dependency or external integration
- Defining security or performance constraints
ADR Format
Each ADR follows this template (based on Michael Nygard's format):
# ADR-NNN: Title
**Status**: [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
**Date**: YYYY-MM-DD
**Deciders**: [List key decision makers]
## Context
What is the issue that we're seeing that is motivating this decision or change?
## Decision
What is the change that we're proposing and/or doing?
## Consequences
What becomes easier or more difficult to do because of this change?
### Positive
- ...
### Negative
- ...
### Neutral
- ...
## Alternatives Considered
### Option 1: Name
**Pros**: ...
**Cons**: ...
**Decision**: Not chosen because...
## References
- [Link to related issues, docs, discussions]
ADR Index
| ADR | Title | Status | Date |
|---|---|---|---|
| 001 | Use Service Proxy Over Direct Access | Accepted | 2025-01-15 |
| 002 | React Context for State Management | Accepted | 2025-01-15 |
| 003 | Drawer Navigation for Namespace Detail | Accepted | 2025-01-18 |
| 004 | Prohibit Direct MUI Imports | Accepted | 2025-01-20 |
Creating a New ADR
- Determine the next ADR number (e.g., if last ADR is 004, new ADR is 005)
- Create a new file:
NNN-short-title.md(e.g.,005-exemption-management.md) - Use the template above and fill in all sections
- Add entry to this README in the ADR Index table
- Submit for review via pull request
ADR Lifecycle
- Proposed: ADR is drafted and under discussion
- Accepted: Decision has been made and is currently in effect
- Deprecated: Decision is no longer recommended but not yet superseded
- Superseded by ADR-XXX: Decision has been replaced by a newer ADR