# 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