Architecture Decision Records

This section documents the key architectural decisions made for the Folionaut project.

What is an ADR?

An Architecture Decision Record (ADR) captures an important architectural decision made along with its context and consequences. ADRs help:

• Document the reasoning behind decisions
• Provide context for future developers
• Enable informed reconsideration of decisions

Summary

ADR	Title	Status	Summary
001	Database Choice	Accepted	Turso (libSQL) for edge-friendly SQLite
002	Caching Strategy	Accepted	Layered Redis/Memory with Token Bucket rate limiting
003	LLM Abstraction	Accepted	Provider abstraction layer for flexibility
004	Repository Pattern	Accepted	Abstract data access for testability
005	Observability	Accepted	Events and OpenTelemetry tracing
006	PII Protection	Accepted	Guardrails-based PII detection and sanitization
007	Content Model	Accepted	Flexible JSON with app-level validation
008	Shared Tools	Accepted	Unified tool implementations for MCP and chat

ADR Template

When adding new ADRs, use this template:

# ADR NNN: Title

## Status

Proposed | Accepted | Deprecated | Superseded

## Context

What is the issue that we're seeing that is motivating this decision?

## Decision

What is the change that we're proposing and/or doing?

## Alternatives Considered

| Option | Pros | Cons |
|--------|------|------|
| Option A | ... | ... |
| Option B | ... | ... |

## Consequences

### Positive
- ...

### Negative
- ...

### Mitigations
- ...

## References
- ...

Decision Themes

Data Layer

• ADR-001: Database Choice - Why Turso
• ADR-004: Repository Pattern - How we access data
• ADR-007: Content Model - Flexible JSON schema

Infrastructure

• ADR-002: Caching Strategy - Redis and rate limiting
• ADR-005: Observability - Events and tracing

AI Integration

• ADR-003: LLM Abstraction - Provider flexibility
• ADR-006: PII Protection - Guardrails and sanitization
• ADR-008: Shared Tools - Unified MCP and chat tools