Free online ADR generator

# ADR: Record architecture decisions as ADRs in the repo

**Status:** Accepted
**Date:** 2026-06-11

## Context

Important technical and process decisions are discussed in PRs, Slack threads, and meetings. Over time the rationale is lost. New engineers and future maintainers have no reliable way to understand why the current state exists.

## Decision

We will write short Architecture Decision Records (ADRs) as Markdown files inside the repository. Files live under docs/adr/ (or adrs/) and follow a consistent lightweight template. Each ADR captures context, the decision, and consequences.

## Consequences

Decisions become part of the permanent, searchable, versioned record. Onboarding is faster. Future refactors can reference prior ADRs instead of rediscovering rationale. The cost per decision is low and the long-term value is high for any team that maintains code over time.

## Alternatives considered

Keep decisions only in wiki pages or Confluence (rejected: pages go stale and live outside the code). Rely on tribal knowledge and PR comments (rejected: impossible to search or audit later). Use a dedicated heavy ADR tool (rejected: adds another system and access friction).

# ADR: Use Mermaid for architecture diagrams instead of images

**Status:** Accepted
**Date:** 2026-06-11

## Context

We previously stored architecture diagrams as PNG and SVG files in the repo and in wikis. They quickly became outdated after refactors, and it was difficult to review or diff changes to the diagrams themselves.

## Decision

All new and updated architecture diagrams will be written in Mermaid syntax inside Markdown files (READMEs, design docs, and ADRs). The diagrams will be rendered by GitHub and by our documentation system.

## Consequences

Diagrams are now editable as text, versioned with the code, and easy to keep in sync. Anyone can propose a change via PR. We lose some pixel-perfect styling control but gain maintainability and reviewability.

## Alternatives considered

Continue with exported images (rejected). Adopt PlantUML or another text format (considered: Mermaid won for native GitHub support and lighter syntax). Use a visual drawing tool only (rejected: same staleness problem).

# ADR: Expose codebase context to AI coding agents over MCP

**Status:** Accepted
**Date:** 2026-06-11

## Context

AI coding tools (Cursor, Claude Code, Copilot, etc.) are increasingly used inside the team. Without good context they waste tokens re-exploring the repo on every prompt and often act on outdated or incomplete information about conventions and gaps.

## Decision

We will run a hosted MCP server (via Moxie Docs) that gives agents compact, citation-backed access to our generated docs, conventions, known documentation gaps, and verified commands. Agents must read context via the MCP tools before proposing edits.

## Consequences

Agents make higher-quality changes with fewer exploratory reads. Documentation updates can be proposed in the same PR as the code change. The context stays fresh because the index updates on every merge. Token usage per task drops.

## Alternatives considered

Paste large context files into every prompt (rejected: quickly stale and wastes tokens). Use a local repo-packing CLI before each session (rejected: manual step, no continuous updates, no gap awareness). Build a custom RAG endpoint (considered but higher maintenance than using an existing MCP host).

# ADR: Run automated Friday documentation reviews and Cleanup PRs

**Status:** Accepted
**Date:** 2026-06-11

## Context

Documentation falls out of date between major refactors. Small changes accumulate and no one remembers to update the corresponding docs. By the time someone notices, the diff is large and the original intent is harder to reconstruct.

## Decision

Every Friday the system will produce a recap of the week's merges and automatically open a single docs-only Cleanup PR when drift or gaps are detected. Team members review and merge (or close) the PR. No documentation change lands without review.

## Consequences

Documentation debt stays bounded. The team develops a weekly habit of reviewing docs the same way they review code. New engineers see both the code evolution and the accompanying doc updates in one place.

## Alternatives considered

Rely on engineers to remember to update docs in every PR (rejected: doesn't scale and leads to drift). Batch all doc work into quarterly cleanups (rejected: the diff becomes unmanageable).