SuperAPI AI Directory

architecture-decision-records

General & other

View repository

Updated 10-16 06:42

About this skill

Architecture Decision Records

Document significant technical decisions so future you (and your team) understands why.

Create an ADR

Standard format

# ADR-001: Use PostgreSQL for primary database

## Status
Accepted

## Date
2024-01-15

Context

We need a primary database for the application. Requirements:

  • Relational data with complex queries
  • Full-text search capability
  • JSON column support for flexible schemas
  • Strong consistency guarantees

Decision

Use PostgreSQL with pgvector extension for vector similarity search.

Alternatives Considered

MySQL

  • Pros: Familiar to team, wide hosting support
  • Cons: Weaker JSON support, no native vector search
  • Rejected: Missing key features we need

MongoDB

  • Pros: Flexible schema, good for document storage
  • Cons: Weaker consistency, complex transactions
  • Rejected: Our data is fundamentally relational

Consequences

  • Team needs PostgreSQL expertise
  • Hosting on Supabase (managed Postgres)
  • pgvector enables future AI/semantic search features
  • Migration path exists if we need to switch (standard SQL)

## Directory Structure

docs/ adr/ 000-template.md 001-use-postgresql.md 002-adopt-nextjs-app-router.md 003-api-authentication-strategy.md README.md # Index of all ADRs


## ADR Index

```bash
# Generate index from ADR files
echo "# Architecture Decision Records" > docs/adr/README.md
echo "" >> docs/adr/README.md
for f in docs/adr/[0-9]*.md; do
  title=$(head -1 "$f" | sed 's/^# //')
  status=$(grep "^## Status" -A1 "$f" | tail -1)
  echo "- [$title]($f) — $status" >> docs/adr/README.md
done

When to Write an ADR

  • Choosing a framework, language, or database
  • Changing authentication/authorization approach
  • Adopting a new deployment strategy
  • Major refactoring decisions
  • Third-party service selection
  • API design decisions (REST vs GraphQL, versioning strategy)

When NOT to Write an ADR

  • Routine bug fixes
  • Minor library version updates
  • Code style changes (use linter config instead)
  • Anything that doesn't affect other developers

Updating ADRs

Don't edit old ADRs. If a decision changes, write a new ADR that supersedes the old one:

## Status
Superseded by [ADR-007](007-switch-to-supabase-auth.md)

Notes

  • ADRs are immutable history. They record what was decided and why at that time.
  • Keep them short. One page is ideal. If it's longer, the decision might be too complex.
  • Store ADRs in the repo, not in a wiki. They should travel with the code.
  • The "Alternatives Considered" section is the most valuable part — it prevents re-litigating decisions.