Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for the Chaos Cypher platform.

What is an ADR?

An ADR documents a significant architectural decision, including:

The context and problem statement
The decision that was made
The rationale and alternatives considered
The consequences (positive and negative)

Format

ADRs are numbered sequentially and follow this naming convention:

NNNN-title-in-kebab-case.md

For example:

0001-remove-discovery-and-lenses-features.md
0002-dependency-license-policy.md
0003-replace-pymupdf-with-pypdf.md
0004-redis-to-valkey-migration.md
0005-ollama-instances-only.md

ADR Template

# [Number]. [Title]

Date: YYYY-MM-DD

## Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]

## 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?

## Rationale

Why did we choose this option? What alternatives did we consider?

## Consequences

### Positive
- What becomes easier?
- What benefits do we gain?

### Negative
- What becomes harder?
- What trade-offs are we making?

### Neutral
- What stays the same?

Current ADRs

ADR	Title	Status	Date
0001	Remove Discovery and Lenses Features	Accepted	2026-02-05
0002	Dependency License Policy	Accepted	2026-02-06
0003	Replace PyMuPDF with pypdf	Accepted	2026-02-06
0004	Migrate from Redis to Valkey	Accepted	2026-03-15
0005	Ollama configuration via instances list only	Accepted	2026-04-08

When to Write an ADR

Create an ADR when making decisions about:

System architecture patterns
Technology choices (languages, frameworks, databases)
API design principles
Data models and schemas
Development workflows
Deployment strategies
Security approaches

Process

Copy the template above
Fill in the sections
Propose the ADR (Status: Proposed)
Discuss with team
Update and mark as Accepted
Commit to git

What is an ADR?​

Format​

ADR Template​

Current ADRs​

When to Write an ADR​

Process​

References​