62 lines
2.2 KiB
Markdown
62 lines
2.2 KiB
Markdown
|
# Architecture Decision Records (ADRs)
|
||
|
|
|
||
|
|
This directory contains Architecture Decision Records (ADRs) for SecretumVault.
|
||
|
|
|
||
|
|
ADRs document significant architectural decisions, their context, alternatives considered, and consequences.
|
||
|
|
|
||
|
|
## Format
|
||
|
|
|
||
|
|
Each ADR follows the [Nygard format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions):
|
||
|
|
|
||
|
|
- **Title**: Short noun phrase describing the decision
|
||
|
|
- **Status**: Proposed, Accepted, Deprecated, Superseded
|
||
|
|
- **Context**: Problem and constraints
|
||
|
|
- **Decision**: What we decided to do
|
||
|
|
- **Consequences**: Positive and negative outcomes
|
||
|
|
|
||
|
|
## ADR Index
|
||
|
|
|
||
|
|
| ADR | Title | Status | Date |
|
||
|
|
|-----|-------|--------|------|
|
||
|
|
| [001](001-post-quantum-cryptography-oqs-implementation.md) | Real Post-Quantum Cryptography Implementation via OQS Backend | ✅ Accepted & Implemented | 2026-01-17 |
|
||
|
|
|
||
|
|
## ADR Lifecycle
|
||
|
|
|
||
|
|
```text
|
||
|
|
Proposed → Accepted → Implemented
|
||
|
|
↓
|
||
|
|
Deprecated (replaced by newer ADR)
|
||
|
|
↓
|
||
|
|
Superseded (points to replacement ADR)
|
||
|
|
```
|
||
|
|
|
||
|
|
## When to Create an ADR
|
||
|
|
|
||
|
|
Create an ADR when making decisions about:
|
||
|
|
|
||
|
|
- **Architecture**: Major structural changes (new backend, engine redesign)
|
||
|
|
- **Technology**: Choosing libraries, frameworks, or tools (OQS vs RustCrypto)
|
||
|
|
- **Patterns**: Establishing coding patterns (wrapper structs, caching strategy)
|
||
|
|
- **Security**: Cryptographic algorithms, authentication methods
|
||
|
|
- **Performance**: Trade-offs between speed and safety
|
||
|
|
- **Compliance**: Standards conformance (NIST FIPS)
|
||
|
|
|
||
|
|
## How to Create an ADR
|
||
|
|
|
||
|
|
1. Copy template from existing ADR (e.g., ADR-001)
|
||
|
|
2. Number sequentially (ADR-002, ADR-003, etc.)
|
||
|
|
3. Use kebab-case filename: `NNN-short-descriptive-title.md`
|
||
|
|
4. Fill in all sections:
|
||
|
|
- Context (why we need to decide)
|
||
|
|
- Decision (what we decided)
|
||
|
|
- Alternatives Considered (what we rejected and why)
|
||
|
|
- Consequences (pros/cons)
|
||
|
|
5. Update this index with new entry
|
||
|
|
6. Submit for review before marking as Accepted
|
||
|
|
|
||
|
|
## Related Documentation
|
||
|
|
|
||
|
|
- [Architecture Overview](../overview.md) - High-level system architecture
|
||
|
|
- [Complete Architecture](../complete-architecture.md) - Detailed architecture reference
|
||
|
|
- [Development Documentation](../../development/README.md) - Build and development guides
|