Architecture Decision Records¶

!!! info "TL;DR" ADRs document significant architectural choices in Canviq. We maintain 21 ADRs covering deployment, authentication, database design, integrations, and the survey system. Each ADR captures the context, decision, and consequences of a choice.

What are ADRs?¶

Architecture Decision Records (ADRs) are lightweight documents that capture important architectural decisions made during the development of Canviq. Each ADR describes:

• Context: The problem or situation requiring a decision
• Decision: The architectural choice made
• Consequences: The implications and tradeoffs of that choice
• Status: Whether it's proposed, accepted, deprecated, or superseded

Why Canviq uses ADRs¶

ADRs serve as a historical record of why the system is built the way it is. They help new contributors understand past decisions, prevent re-litigating settled questions, and make it easier to evaluate whether an ADR's assumptions still hold.

When significant architectural changes are proposed, we write an ADR to document the decision-making process.

All ADRs¶

Deployment & Infrastructure¶

• ADR-0001: Standalone Deployment — Separate Vercel and Supabase projects from core site
• ADR-0002: Standalone Authentication — Independent user accounts, no shared auth with core site

Data & Search¶

• ADR-0003: PostgreSQL Full-Text Search — Use tsvector instead of external search services
• ADR-0004: Supabase Realtime — Live updates for votes, comments, and status changes
• ADR-0006: Denormalized Counts — Database triggers maintain vote_count for performance
• ADR-0013: Duplicate Detection — Full-text similarity scoring for duplicate submissions

Security & Authorization¶

• ADR-0007: Row-Level Security — Supabase RLS policies for authorization
• ADR-0009: Rate Limiting — In-memory rate limiting for user actions
• ADR-0010: Spam Detection — Content moderation and moderation queue
• ADR-0015: Security Controls — Audit logging, MFA, and SOC 2 readiness
• ADR-0019: Agent Identity & Access Management — API key authentication and scoped permissions for AI agents

Integrations & Notifications¶

• ADR-0008: GitHub Integration — One-way issue creation from submissions
• ADR-0011: Email Notifications — Resend for transactional emails

Internationalization¶

• ADR-0005: Internationalization Strategy — next-intl with JSONB for multilingual content

Workflows & Status¶

• ADR-0012: Submission Status Workflow — 7-status enum lifecycle
• ADR-0020: Workflow Automation Engine — Inngest for durable execution and action handlers

Compliance¶

• ADR-0014: GDPR Compliance — Cookie consent, data export, and account deletion

Survey System¶

• ADR-0016: Survey System Schema — 15+ tables for questions, targeting, and responses
• ADR-0017: MCP Server Architecture — HTTP + SSE transport with tool registry
• ADR-0018: SDK Monorepo Strategy — Turborepo and Changesets for SDK distribution
• ADR-0021: Sentiment Analysis Integration — Claude Haiku for survey response analysis

Documentation¶

• ADR-0034: Documentation Site — MkDocs Material for public documentation

What's next¶

• Browse individual ADRs to understand specific decisions
• See Contributing to learn how to propose new ADRs
• Check the Changelog for recent architectural changes