This index helps you navigate all Forms Platform documentation.
New to the project? Start here:
- README.md - Project overview and setup
- AGENTS.md - AI agent guidelines and repository structure
- Quick Reference - Common commands and workflows
- Architecture Overview - System design and component relationships
Using Claude Code? See CLAUDE.md for Claude-specific guidance.
Core Concepts
- Architecture Overview - System design, packages, data flows
- Terminology - Domain language (blueprints, patterns, prompts, components)
- DOJ Deployment Diagram - Department of Justice specific architecture
Patterns & Conventions
- Patterns and Conventions - Coding standards, naming, architecture patterns
- Pattern System - Form building blocks and pattern usage
Getting Started
- Quick Reference - Common commands, workflows, troubleshooting
- Podman Integration - Development environment setup with Podman/Docker
Package Documentation
- Forms Package - Core business logic, services, patterns
- Design Package - UI components and Storybook
- Server Package - Node.js web server (Astro + Express)
- Auth Package - Authentication and authorization
- Database Package - PostgreSQL/SQLite with Kysely and Knex
- Common Package - Shared utilities
Application Documentation
- Spotlight App - Main Astro website
- CLI App - Command-line interface
- Sandbox App - Testing and demo application
- Server DOJ App - Department of Justice server instance
Testing
- E2E Testing - Playwright end-to-end tests
- ADR 0010: End-to-End Testing - E2E testing strategy
Release and Deployment
- Release Process - How to release new versions
- ADR 0003: Initial Deployment Choices
- ADR 0004: Infrastructure as Code
Infrastructure
- AWS CDK Infrastructure - AWS deployment
- Terraform CDK Infrastructure - Terraform deployment
- Core Infrastructure - Shared infrastructure utilities
Security
All architectural decisions are documented as ADRs in documents/adr/. Key decisions:
System Architecture
- ADR 0001: Record Architecture Decisions
- ADR 0005: Build System - Turborepo + pnpm workspaces
- ADR 0013: Database Strategy - PostgreSQL, SQLite, Kysely, Knex
- ADR 0015: REST API
- ADR 0018: Documentation Strategy
Frontend & Design
- ADR 0006: Spotlight Frontend - Astro framework
- ADR 0007: Initial CSS Strategy
- ADR 0009: Design Assets Workflow
- ADR 0012: Rich Text Editor
- ADR 0016: Unused CSS
Code Quality
Domain Logic
Sample Documents
Work in Progress
- Pending Loose Ends - Known gaps and future work
When making code changes:
- Update relevant documentation in the same PR
- Create ADR for significant architectural decisions
- Update package READMEs when public APIs change
- Keep this index current when adding new documentation
See ADR 0018: Documentation Strategy for complete guidelines.