README.md

Documentation

This directory contains all project documentation organized by topic.

Quick Links

Getting Started

• Install TOPS - the canonical setup path, in the repository README
• Laravel App Setup - Detailed setup instructions

Architecture & Planning

• Roadmap - The plan of record. Now / Next / Later, user stories, and the decisions log
• Architecture - System architecture and design decisions
• AWS Scanner Coverage & Research - Which AWS services and misconfigurations to scan, current rule coverage, CIS alignment, and the staged plan for expanding it
• Docker self-hosted deployment session (2026-06-21) - ECS/Lambda assessment, Docker Compose Phases 1–2, installer, region wiring

Features

• Feature Specifications - All feature specifications and user stories
• AWS Account Onboarding Flow - Detailed onboarding process

Laravel Application

• Laravel App Documentation - Laravel-specific documentation
• API Documentation - API endpoints reference
• Database Architecture - Database schema and design
• Environment Setup - Environment variables guide
• OAuth Setup - Firebase OAuth configuration
• Email Verification - Email verification setup
• Queue Setup - Background job processing

Development

• Feature Development Process - How to develop features
• Practices Checklist - Development practices checklist
• User Story Template - Template for writing user stories

AI Coding Assistants

The practices below are the single source of truth. These files load them into an assistant's context automatically so no session starts without them:

• CLAUDE.md - loaded into every Claude Code session
• .cursor/rules/ - loaded into every Cursor request; 00-practices.mdc always applies, the others attach by file path
• .claude/skills/ - on-demand skills: feature-development drives the six-phase process, practices-review checks a diff against the checklist, run-tests covers the suite and its Docker fallback
• .claude/settings.json - informational hooks that surface the practices at session start and on feature-shaped prompts

Keep these in sync when the practices change - they summarise and link, they do not duplicate.

Practices

• Product Practices - Product development practices
• Architecture Practices - Architecture guidelines
• Security Practices - Security best practices
• Testing Practices - Testing guidelines
• Code Quality - Code quality standards
• Database Practices - Database design practices

Progress & Status

• Progress Tracking - Feature completion status, known gaps, and open-source readiness. Records state; the roadmap records plan

Documentation Structure

docs/
├── README.md (this file)
├── architecture.md
├── planning.md
├── PROGRESS.md
├── laravel-app/          # Laravel application documentation
│   ├── README.md
│   ├── setup.md
│   ├── API_DOCUMENTATION.md
│   └── ...
├── features/            # Feature specifications
│   ├── features-spec.md
│   └── onboarding-flow.md
├── design/              # Design documentation
│   └── wireframes.md
├── processes/           # Development processes
│   ├── feature-development.md
│   └── practices-checklist.md
├── practices/           # Development practices
│   ├── product.md
│   ├── architecture.md
│   └── ...
└── templates/           # Document templates
    └── user-story-template.md

Contributing to Documentation

When adding new documentation:

1. Place it in the appropriate subdirectory
2. Update this README with a link
3. Follow existing documentation patterns
4. Keep documentation up to date with code changes