CAIRL Documentation

Welcome to the CAIRL documentation. This directory contains all technical documentation, architectural decisions, specifications, and operational procedures.

Directory Structure

docs/
├── README.md                                    # This file
├── PIPELINE.md                                  # CI/CD pipeline documentation
│
├── governance/                                  # Documentation governance
│   ├── doc-authority.md                        # Documentation authority and ownership
│   └── naming-and-versioning.md                # Naming conventions and versioning
│
├── decisions/                                   # Architecture Decision Records (ADRs)
│   ├── 001-tech-stack.md                       # Technology stack selection
│   ├── 007-git-workflow.md                     # Git workflow decisions
│   └── 008-conventional-commits.md             # Commit message standards
│
├── contracts/                                   # Engineering contracts and standards
│   ├── engineering-principles.md               # Core development principles
│   ├── ui-copy-and-tone.md                     # Brand and UX guidelines
│   ├── authz-and-roles.md                      # Authorization model
│   ├── rls-standard.md                         # Row Level Security standards
│   ├── data-retention.md                       # Data retention policies
│   └── rate-limits-and-abuse.md                # Rate limiting and abuse prevention
│
├── architecture/                                # System architecture
│   ├── system-overview.md                      # High-level architecture
│   ├── data-architecture.md                    # Data models and flows
│   ├── database-schema.md                      # Database schema documentation
│   ├── aws-setup.md                            # AWS infrastructure setup
│   ├── ci-cd-pipeline.md                       # CI/CD architecture
│   └── observability-plan.md                   # Monitoring and logging
│
├── roadmap/                                     # Product roadmap
│   └── product-roadmap.md                      # Product development roadmap
│
├── specs/                                       # Feature specifications
│   ├── template.spec.md                        # Specification template
│   └── mailgap/
│       └── mailgap-proxy-email-service.spec.md # MailGap service specification
│
├── flows/                                       # User flows
│   ├── template.flow.new.md                    # Flow template
│   └── mailgap/
│       └── mailgap-reply.flow.new.md           # MailGap reply flow
│
├── testing/                                     # Testing documentation
│   └── uat/
│       ├── phase-2-testing-script.md           # UAT phase 2 script
│       ├── phase-2-automated-results.md        # UAT phase 2 results
│       └── phase-3-automated-results.md        # UAT phase 3 results
│
├── workflow/                                    # Development workflow
│   ├── contributing.md                         # Contribution guidelines
│   ├── git-workflow.md                         # Git branching strategy
│   └── branch-protection.md                    # Branch protection rules
│
└── runbooks/                                    # Operational procedures
    ├── provider-outage.new.md                  # Provider outage response
    └── allowlist-approvals.new.md              # Allowlist approval process

Document Categories

Governance

Documentation about documentation - authority, ownership, naming conventions, and versioning standards.

Decisions (ADRs)

Architecture Decision Records document significant technical decisions and their rationale. Follow the ADR template for consistency.

Contracts

Engineering contracts define unchanging principles and standards that all development must follow:

• Engineering principles and code quality
• UI/UX guidelines and brand standards
• Security and authorization models
• Data handling policies

Architecture

System design documentation covering infrastructure, data models, and technical architecture.

Roadmap

Product development roadmap and feature planning.

Specs

Detailed feature specifications following the specification template. Organized by feature area.

Flows

User flow documentation describing end-to-end user journeys. Organized by feature area.

Testing

Testing strategies, UAT scripts, and test results.

Workflow

Development workflow documentation including Git strategies, contribution guidelines, and CI/CD processes.

Runbooks

Operational procedures for incident response, maintenance, and administrative tasks.

Document Conventions

File Naming

• Lowercase with dashes: file-name.md
• Descriptive names: Clear indication of content
• New documents: Use .new.md extension for placeholders
• Versioned documents: Use sequential numbers for ADRs (001, 002, etc.)

Templates

Use provided templates for new documents:

• Specification Template
• Flow Template
• ADR format in existing ADR files

Status Indicators

Documents should include status:

• Draft: Work in progress
• Review: Ready for review
• Approved: Reviewed and approved
• Active: Current and authoritative
• Deprecated: Superseded by newer document

Contributing

Adding New Documentation

1. Check if template exists for document type
2. Copy template and rename appropriately
3. Fill in content following template structure
4. Update this README if adding new category
5. Create PR for review

Updating Existing Docs

1. Check "Last Updated" date
2. Make changes with clear intent
3. Update "Last Updated" date
4. Create PR with descriptive commit message

Placeholder Documents

Documents with .new.md extension are placeholders awaiting content. These indicate areas where documentation is needed.

Quick Links

External Documentation

• Next.js Docs
• Drizzle ORM Docs
• Tailwind CSS Docs
• shadcn/ui Docs
• PostgreSQL Docs
• Supabase Docs

Project Files

• Main README
• CLAUDE.md - AI assistant development guide
• Database Schema
• Tailwind Config

Documentation Status

Maintained by: CAIRL Engineering Team Last Updated: 2026-02-06 Completion: 100% (29/29 documents complete)