Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/karolswdev/hoa-management-system

My attempt at creating an HOA Management System
https://github.com/karolswdev/hoa-management-system

Last synced: 4 months ago
JSON representation

My attempt at creating an HOA Management System

Awesome Lists containing this project

README 

          
# HOA Community Hub



[![CI](https://github.com/karolswdev/hoa-management-system/actions/workflows/ci.yml/badge.svg)](https://github.com/karolswdev/hoa-management-system/actions/workflows/ci.yml)

[![Secret Scan](https://github.com/karolswdev/hoa-management-system/actions/workflows/gitleaks.yml/badge.svg)](https://github.com/karolswdev/hoa-management-system/actions/workflows/gitleaks.yml)

[![CodeQL](https://github.com/karolswdev/hoa-management-system/actions/workflows/codeql.yml/badge.svg)](https://github.com/karolswdev/hoa-management-system/actions/workflows/codeql.yml)

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

[![Dependabot](https://img.shields.io/badge/Dependabot-enabled-brightgreen?logo=dependabot)](./.github/dependabot.yml)



Welcome to the HOA Community Hub, a modern, full-stack web application designed to be the central digital point of contact for a Homeowners' Association and its residents. This platform streamlines communication, simplifies document access, manages community events, and provides essential administrative tools.



## Live



- Production: https://sandersoncreekhoa.com/

- API base: https://sandersoncreekhoa.com/api/

- Health: https://sandersoncreekhoa.com/api/health



Notes

- Nginx enforces HTTPS and redirects `www.sandersoncreekhoa.com` → `sandersoncreekhoa.com`.

- Turnstile is enabled on Registration; SendGrid handles outbound email.



## Table of Contents



1.  [Vision & Purpose](#vision--purpose)

2.  [Core Features](#core-features)

3.  [Technology Stack](#technology-stack)

4.  [Project Structure](#project-structure)

5.  [Getting Started](#getting-started)

    - [Prerequisites](#prerequisites)

    - [Backend Setup](#backend-setup)

    - [Frontend Setup](#frontend-setup)

6.  [Running the Application](#running-the-application)

7.  [Running Tests](#running-tests)

8.  [API Documentation](#api-documentation)

9.  [CI/CD Pipeline](#cicd-pipeline)

10. [Deployment (Production)](#deployment-production)

11. [Contributing & Security](#contributing--security)



---



## Vision & Purpose



The goal of the HOA Community Hub is to replace fragmented communication channels like email chains and paper notices with a single, secure, and user-friendly platform. It empowers community administrators with the tools they need to manage the HOA efficiently while providing residents with easy access to information and a forum for discussion.



**User Personas:**

*   **Administrator:** Manages users, content, site configuration, and feature rollouts via flags.

*   **Resident (Member):** Accesses information, participates in discussions, votes in polls, and searches vendor directory.

*   **Guest:** Views public-facing information about the HOA and public vendor categories.



**Recent Enhancements (Iteration 5):**

- Finalized CI/CD automation with health gate validation before registry pushes

- Enhanced health monitoring endpoints (`/healthz`, `/metrics`) with diagnostics payloads

- Completed cross-module QA and accessibility suite verification (WCAG 2.1 AA compliance)

- Comprehensive documentation and knowledge transfer artifacts

- Release communications templates and feature flag operational runbooks



---



## Core Features



| Feature                | Administrator (`admin`)                                      | Resident (`member`)                                  | Guest (Unauthenticated)     |

| ---------------------- | ------------------------------------------------------------ | ---------------------------------------------------- | --------------------------- |

| **Authentication**     | ✅ Login/Logout                                              | ✅ Login/Logout, Register, Email Verify, Password Reset | ❌                       |

| **User Management**    | ✅ View, Approve/Reject, Change Role, Delete Users           | ✅ Manage Own Profile                                | ❌                          |

| **Announcements / HOA Messages** | ✅ Create, Edit, Delete, Optional Email Notify to All Members | ✅ View                                              | ❌                          |

| **Events**             | ✅ Create, Edit, Delete                                      | ✅ View                                              | ❌                          |

| **Documents**          | ✅ Upload, Manage, Set Visibility                            | ✅ View & Download Approved Docs                     | ✅ View & Download Public Docs |

| **Discussions**        | ✅ Delete Threads/Replies                                    | ✅ Create/View Threads, Post Replies                 | ❌                          |

| **Site Configuration** | ✅ Edit Site Name/Description                                | ❌                                                   | ❌                          |

| **Audit Logs**         | ✅ View all administrative actions                           | ❌                                                   | ❌                          |

| **Email**              | ✅ SendGrid provider, approval/rejection, announcements, password reset, email verification | — | — |

| **CAPTCHA**            | —                                                           | ✅ Registration protected by Turnstile               | — |

| **Accessibility**      | ✅ Configure default high-vis mode                          | ✅ Toggle high-visibility theme, keyboard navigation | ✅ High-vis mode support    |

| **Feature Flags**      | ✅ Runtime configuration, staged rollouts                   | ❌                                                   | ❌                          |



---



## Technology Stack



*   **Backend:**

    *   **Framework:** Node.js with Express.js

    *   **Database:** SQLite3 (for simplicity and portability)

    *   **ORM:** Sequelize

    *   **Authentication:** JSON Web Tokens (JWT) + Email verification

    *   **Testing:** Jest & Supertest

    *   **Email:** SendGrid (adapter-based service)

    *   **CAPTCHA:** Cloudflare Turnstile (registration)

*   **Frontend:**

    *   **Framework:** React.js with TypeScript

    *   **UI Library:** Material-UI (MUI)

    *   **Routing:** React Router

    *   **State Management:** React Context API

    *   **Form Handling:** Formik & Yup

    *   **API Client:** Axios



---



## Project Structure



The project is a monorepo containing distinct `backend` and `frontend` applications.



## Getting Started



### Prerequisites



*   Node.js (v18.x or later recommended)

*   npm (v10.x or later recommended)



### Backend Setup



1.  **Navigate to the backend directory:**

    ```bash

    cd backend

    ```



2.  **Install dependencies:**

    ```bash

    npm install

    ```



3.  **Set up environment variables:**

    Create a `.env` file in the `backend/` directory by copying the example.

    ```bash

    # You can manually create a .env file and add the following:

    # A strong, secret key for signing JWTs

    JWT_SECRET=your_super_secret_key_here_123!

    JWT_EXPIRES_IN=8h



    # Default admin credentials for the initial database seed

    ADMIN_EMAIL=admin@example.com

    ADMIN_PASSWORD=AdminPassword123!



    # Email provider (SendGrid)

    EMAIL_PROVIDER=sendgrid

    EMAIL_FROM=no-reply@your-domain.com

    EMAIL_FROM_NAME=HOA Community Hub

    SENDGRID_API_KEY=your_sendgrid_api_key



    # Frontend base (for email links)

    FRONTEND_BASE_URL=http://localhost:3000



    # Password reset cooldown (minutes)

    PASSWORD_RESET_COOLDOWN_MINUTES=60



    # CAPTCHA (Cloudflare Turnstile)

    TURNSTILE_SECRET_KEY=your_turnstile_secret

    ```



4.  **Run database migrations and seeders:**

    This command will create the database schema and populate it with an initial admin user and default site configuration.

    ```bash

    npm run db:migrate

    npm run db:seed

    ```



### Frontend Setup



1.  **Navigate to the frontend directory:**

    ```bash

    # from the project root

    cd frontend

    ```



2.  **Install dependencies:**

    ```bash

    npm install

    ```



3.  **Create `.env` (optional but recommended):**

    ```bash

    VITE_API_BASE_URL=http://localhost:3001/api

    # Turnstile site key (if protecting registration locally)

    VITE_TURNSTILE_SITE_KEY=your_turnstile_site_key

    VITE_APP_VERSION=1.0.0

    # App name for document.title

    VITE_APP_NAME=Sanderson Creek HOA

    ```



---



## Running the Application



You will need two separate terminal windows to run the backend and frontend servers concurrently.



1.  **Start the Backend Server:**

    ```bash

    # In a terminal, from the backend/ directory

    npm start

    ```

    The API will be running on `http://localhost:3001`.



2.  **Start the Frontend Development Server:**

    ```bash

    # In a second terminal, from the frontend/ directory

    npm run dev

    ```

    The React application will open in your browser, usually at `http://localhost:3000`. (CI uses a `npm run dev:screenshots` variant that binds to `0.0.0.0:3000` when generating automated screenshots.)



Notes

- Registration requires email verification. Users must click the link sent via email. Admin approval is also required to access member features.

- “Forgot password” is limited to once per hour per account (configurable via `PASSWORD_RESET_COOLDOWN_MINUTES`).

- Admins can optionally email an announcement to all approved, verified members by checking the “Email this announcement…” box in the admin UI.



---



## Running Tests



The project includes comprehensive test coverage for both backend and frontend components, enforced by CI/CD pipelines.



### Backend Tests



*   **Integration tests with coverage:**

    ```bash

    # From the backend/ directory

    npm run test:integration -- --coverage

    ```

    This includes tests for password reset rate limiting, announcement email notifications (mocked), and vote hashchain integrity.



*   **Specific test file (debugging):**

    ```bash

    # From the backend/ directory

    npm run test:debugging -- test/debugging/users.test.js

    ```



*   **Hashchain integrity tests:**

    ```bash

    npx jest --testPathPattern=poll.test.js --testNamePattern="(integrity|hashchain|tamper)"

    ```



### Frontend Tests



*   **Unit tests with coverage:**

    ```bash

    # From the frontend/ directory

    npm run test:coverage

    ```



*   **Accessibility tests (WCAG 2.1 AA compliance):**

    ```bash

    npm run test -- src/tests/*.a11y.test.tsx

    ```



*   **Interactive test UI:**

    ```bash

    npm run test:ui

    ```



*   **E2E screenshot generation for user guides:**

    ```bash

    # From the repository root

    npm run --prefix frontend generate-screenshots

    ```

    That command sets `GENERATE_SCREENSHOTS=true` so Playwright captures every page, and our CI workflow (`.github/workflows/generate-screenshots.yml`) mirrors the same steps, starts both dev servers (backend on 5000, frontend on 3000), and publishes the screenshots as workflow artifacts.



---



## Deployment (Production)



For repeatable deployments to a remote server via SSH (backups, code sync, Docker image build, minimal downtime restarts, and verification), use the helper scripts in `deploy/`:



- `deploy/deploy.local.sh` – run locally; syncs code to the remote and invokes the remote routine.

- `deploy/remote.deploy.sh` – runs on the server; creates backups, builds, restarts, runs migrations (optional), and verifies.

- `deploy/config.example.env` – copy to `deploy/config.env` and set `DEPLOY_HOST`, `DEPLOY_USER`, `SSH_KEY`, `REMOTE_DIR`, `DOMAIN`, `BACKEND_IMAGE`, `FRONTEND_IMAGE`, and flags like `RUN_MIGRATIONS`.

- `deploy/DEPLOY.md` – full details and quick start.



Environment (production highlights)

- Backend: `JWT_SECRET`, `JWT_EXPIRES_IN`, `EMAIL_PROVIDER=sendgrid`, `EMAIL_FROM`, `EMAIL_FROM_NAME`, `SENDGRID_API_KEY`, `FRONTEND_BASE_URL`, `PASSWORD_RESET_COOLDOWN_MINUTES`, `TURNSTILE_SECRET_KEY`.

- Frontend build: `VITE_API_BASE_URL`, `VITE_APP_NAME`, `VITE_TURNSTILE_SITE_KEY`, `VITE_APP_VERSION` (the release workflow injects the git tag).



### GitHub Actions Release Workflow with Health Gate



The deployment pipeline implements a **health gate pattern** where Docker images are validated before being pushed to the container registry:



1. **Build Phase:**

   - Publish a GitHub release (or dispatch the workflow manually) to trigger automated build

   - Workflow builds backend and frontend images with `docker buildx`

   - Images tagged as `ghcr.io//hoa-backend:` and `ghcr.io//hoa-frontend:`



2. **Health Gate Validation:**

   - Images loaded locally on GitHub Actions runner (not pushed yet)

   - Temporary containers started with test database

   - Database migrations executed and validated

   - Health endpoints (`/api/health`, `/api/metrics`) verified with retries

   - Container logs captured as workflow artifacts (`health-gate-dry-run-logs`)



3. **Registry Push (Only After Health Gate Pass):**

   - Images pushed to GHCR using built-in `GITHUB_TOKEN`

   - Failed health checks prevent bad images from reaching production

   - Artifacts retained for 30 days for troubleshooting



4. **Deployment to Linode:**

   - SSH orchestration pulls verified images from GHCR

   - Automated backups (database, uploads, code) before deployment

   - Zero-downtime restarts via Docker Compose

   - Post-deploy verification of health endpoints



**Required repository secrets:** `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_DIR`, `DEPLOY_DOMAIN`, `DEPLOY_SSH_KEY`, `VITE_TURNSTILE_SITE_KEY`



**Detailed Documentation:**

- [Deployment Runbook](docs/runbooks/deployment.md) – Complete deployment procedures, health gate details, rollback steps

- [Release Checklist](docs/runbooks/release-checklist.md) – Pre-deploy, deploy, and post-deploy verification checklists

- [Feature Flags Runbook](docs/runbooks/feature-flags.md) – Runtime configuration and staged rollout procedures

- [Release Communications](docs/runbooks/release-communications.md) – Stakeholder communication templates



### Nginx



- Example site config lives on the server; ensure HTTPS, redirect `www` → apex, and a strict CSP that allows `https://challenges.cloudflare.com` for Turnstile.

- The app's Docker Compose publishes backend on `127.0.0.1:3001` and frontend on `127.0.0.1:3000`; Nginx proxies `https:///api/` to backend and `/` to frontend.



---



## HOA Message Feature



### Overview



The HOA Message feature allows administrators to send important communications to all HOA members via email. This is implemented through the announcements system with email notification capabilities.



### How It Works



When creating an announcement, administrators can enable the **"Notify Members"** option to send the announcement via email to all approved, verified, and active HOA members.



**API Endpoint**: `POST /api/announcements`



**Request Body**:

```json

{

  "title": "Important HOA Update",

  "content": "
This is an important message for all members.
",

  "notify": true,

  "expiresAt": "2025-12-31T23:59:59Z"

}

```



**Notification Behavior**:

- Emails are sent to all users with:

  - `status: 'approved'`

  - `email_verified: true`

  - `is_system_user: false`

- Uses the `announcement.html` email template

- Emails are sent sequentially with error handling

- Failed emails don't prevent announcement creation



### Usage



1. **Admin logs in** to the system

2. **Navigate to Announcements** section

3. **Click "Create Announcement"**

4. **Fill in announcement details**:

   - Title: Subject of the message

   - Content: HTML-formatted message body

   - Expires At: Optional expiration date

   - **Notify Members**: Check this box to send emails

5. **Submit** the announcement



Members will receive an email with the announcement content and a link to view it on the website.



### Implementation Details



**Backend**: `backend/src/services/announcement.service.js` (lines 54-85)



The email sending logic:

- Queries all eligible recipients from the database

- Renders the announcement email template

- Sends individual emails via SendGrid

- Continues on email failures (graceful degradation)



**Email Template**: `backend/src/emails/templates/announcement.html`



### Rate Limiting



Mass email sending is not currently rate-limited, but individual announcement creation follows standard API rate limits (100 requests per 15 minutes per IP).



### Future Enhancements



Potential improvements for a dedicated HOA Message feature:

- Recipient targeting (specific user groups, roles)

- Message scheduling

- Delivery tracking and read receipts

- Template management

- Message history and archive

- Background job processing for large recipient lists



---



## Production Readiness



The HOA Management System includes comprehensive production-ready features for monitoring, security, and operations.



### Security Features



- **Rate Limiting**:

  - Global API rate limiting (100 req/15min)

  - Login attempts: 5 per IP+email per 15 minutes

  - Registration: 3 per IP per hour

  - Password reset: 3 per IP+email per hour

- **CORS Protection**: Configurable allowed origins

- **Input Validation**: Joi validation on all endpoints

- **SQL Injection Prevention**: Parameterized queries via Sequelize

- **XSS Protection**: DOMPurify content sanitization

- **JWT Authentication**: Secure token-based auth

- **CAPTCHA**: Cloudflare Turnstile on registration

- **Audit Logging**: All admin actions logged



### Monitoring & Observability



#### Prometheus Metrics

- HTTP request rates and durations

- Error rates by endpoint

- Authentication attempts

- Email sending metrics

- System resources (CPU, memory)

- Database query performance



**Endpoint**: `GET /api/metrics`



#### Grafana Dashboards

- Real-time performance visualization

- Response time percentiles (p50, p90, p95, p99)

- Error tracking

- Business metrics



**Access**: `http://your-server:3002` (default: admin/admin)



#### Structured Logging

- Winston logger with JSON format

- Daily log rotation

- Separate log levels (error, warn, info, http, debug)

- Log files in `backend/logs/`



**Start Monitoring Stack**:

```bash

docker-compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d

```



#### Error Tracking (Optional)

- Sentry integration for automatic error reporting

- Stack traces and user context

- Performance monitoring

- Configure via `SENTRY_DSN` environment variable



**Documentation**: See [docs/MONITORING.md](docs/MONITORING.md)



### Backup & Recovery



#### Automated Backups



Comprehensive backup script (`scripts/backup.sh`) that backs up:

- Database (SQLite, compressed)

- Uploaded documents

- Application logs

- Git commit information

- Configuration (secrets redacted)



**Setup Automated Backups**:

```bash

# Test the backup script

./scripts/backup.sh



# Add to crontab for daily backups at 2 AM

crontab -e

# Add: 0 2 * * * /path/to/hoa-management-system/scripts/backup.sh

```



**Configuration**:

- `BACKUP_DIR`: Backup location (default: `/root/hoa-backups`)

- `BACKUP_RETENTION_DAYS`: Keep backups for N days (default: 30)

- `BACKUP_NOTIFICATION_EMAIL`: Optional email notifications



#### Restore Procedures



Interactive restore script (`scripts/restore.sh`):

```bash

# Interactive mode

./scripts/restore.sh



# Restore specific backup

./scripts/restore.sh 20250111_020000

```



**Documentation**: See [docs/BACKUP_AND_RESTORE.md](docs/BACKUP_AND_RESTORE.md)



### Incident Response



Comprehensive runbook for handling common incidents:

- Application downtime

- Database issues

- Performance degradation

- Security incidents

- Email service failures

- Disk space issues



**Documentation**: See [docs/INCIDENT_RESPONSE.md](docs/INCIDENT_RESPONSE.md)



### Testing



#### Frontend Unit Tests

```bash

cd frontend

npm test                # Run tests

npm run test:coverage   # Generate coverage report

npm run test:ui         # Open Vitest UI

```



Framework: Vitest + React Testing Library



#### End-to-End Tests

```bash

cd frontend

npm run test:e2e        # Run E2E tests

npm run test:e2e:ui     # Open Playwright UI

npm run test:e2e:debug  # Debug mode

```



Framework: Playwright



#### Backend Integration Tests

```bash

cd backend

npm run test:integration

npm run test:debugging

```



Framework: Jest + Supertest



### Environment Variables



#### Required Production Variables

```bash

# Security

JWT_SECRET=your-secret-here

ALLOWED_ORIGINS=https://yourdomain.com



# Email

EMAIL_PROVIDER=sendgrid

SENDGRID_API_KEY=your-api-key

EMAIL_FROM=no-reply@yourdomain.com

EMAIL_FROM_NAME=Your HOA Name

FRONTEND_BASE_URL=https://yourdomain.com



# Turnstile CAPTCHA

TURNSTILE_SECRET_KEY=your-secret-key

VITE_TURNSTILE_SITE_KEY=your-site-key

VITE_APP_VERSION=1.0.0

```



#### Optional Production Variables

```bash

# Monitoring

SENTRY_DSN=https://your-sentry-dsn

SENTRY_TRACES_SAMPLE_RATE=0.1

APP_VERSION=1.0.0



# Logging

LOG_LEVEL=info

ENABLE_FILE_LOGGING=true

LOGS_DIR=./logs



# Backup

BACKUP_DIR=/root/hoa-backups

BACKUP_RETENTION_DAYS=30

BACKUP_NOTIFICATION_EMAIL=admin@yourdomain.com



# Grafana

GRAFANA_ADMIN_USER=admin

GRAFANA_ADMIN_PASSWORD=your-secure-password

```



See `.env.example` for complete list.



---



## CI/CD Pipeline



The project uses GitHub Actions for continuous integration and deployment. All pull requests must pass comprehensive quality gates before merging.



### Pipeline Jobs



The CI workflow (`.github/workflows/ci.yml`) runs 10 parallel jobs:



**Backend Quality Checks:**

- **Lint:** ESLint with strict error enforcement

- **Tests:** Jest integration tests with 80% coverage threshold

- **Hashchain Integrity:** Vote tampering detection and integrity validation

- **Security Audit:** npm audit with critical vulnerability blocking



**Frontend Quality Checks:**

- **Lint:** ESLint + TypeScript type checking

- **Tests:** Vitest unit tests with 75% coverage threshold

- **Accessibility:** WCAG 2.1 AA compliance via axe-core

- **Security Audit:** npm audit with critical vulnerability blocking



**Security & Hygiene:**

- **Hygiene:** Prevents `.env` file commits and scans for hardcoded secrets

- **Aggregate:** Final summary job ensuring all checks passed



### Viewing CI Results



**Status Badge:**

The CI badge at the top of this README shows current pipeline status.



**Artifacts:**

Failed runs produce downloadable artifacts (30-day retention):

- Coverage reports (HTML + JSON)

- Lint logs (JSON format)

- Security audit reports

- Accessibility violation reports

- Test results



**Troubleshooting:**

For detailed troubleshooting guides, see [docs/runbooks/ci-pipeline.md](./docs/runbooks/ci-pipeline.md).



### Running CI Locally



Replicate CI checks locally before pushing:



```bash

# Backend

cd backend

npm ci

npx eslint .

NODE_ENV=test npx sequelize-cli db:migrate

npm run test:integration -- --coverage

npm audit --audit-level=critical



# Frontend

cd frontend

npm ci

npm run lint

npm run test:coverage -- --run

npm run test -- --run src/tests/*.a11y.test.tsx

npm audit --audit-level=critical

```



### Coverage Thresholds



- **Backend:** 80% lines, statements, functions, branches

- **Frontend:** 75% lines, statements, functions, branches



Coverage below thresholds blocks merge. Download coverage artifacts to identify untested code paths.



### Security Policy



- Critical vulnerabilities block CI immediately

- Dependabot alerts must be triaged within 48 hours

- No `.env` files may be committed to the repository

- Secret scanning runs on every push



---



## Contributing & Security



- See [CONTRIBUTING](CONTRIBUTING.md) for guidelines.

- Review our [SECURITY](SECURITY.md) policy for responsible disclosure.

- License: [MIT](LICENSE).



---



## Infrastructure



See docs/INFRASTRUCTURE.md for:

- Cloud/OS details, domains, and TLS

- Nginx proxying (ports, logs, CSP)

- Docker/Compose service layout and persistence paths

- Health endpoints and backup locations



---



## Operational Documentation & Knowledge Transfer



Comprehensive operational documentation is maintained to support volunteer HOA board members and system operators. All documentation follows anchor-based cross-referencing for traceability to architectural decisions and implementation plans.



### Runbooks



**Core Operational Procedures:**

- [Deployment Runbook](docs/runbooks/deployment.md) – Health gate validation, rollback procedures, troubleshooting

- [Release Checklist](docs/runbooks/release-checklist.md) – Pre-release, deployment, and post-deployment verification steps

- [Feature Flags Runbook](docs/runbooks/feature-flags.md) – Runtime configuration, staged rollouts, emergency kill switches

- [Release Communications](docs/runbooks/release-communications.md) – Stakeholder communication templates and timelines

- [CI Pipeline Runbook](docs/runbooks/ci-pipeline.md) – Continuous integration troubleshooting and local replication

- [Health Monitor Runbook](docs/runbooks/health-monitor.md) – Health endpoint diagnostics and monitoring setup



**Module-Specific Runbooks:**

- [Vendor Moderation](docs/runbooks/vendor-moderation.md) – Vendor approval workflows and moderation queue management

- [Notification Log](docs/runbooks/notification-log.md) – Email audit logging and retention policies

- [Pilot Instructions](docs/runbooks/pilot-instructions.md) – Feature pilot program procedures



### Design Documentation



**Accessibility & UI/UX:**

- [Accessibility Suite Design](docs/design/accessibility-suite.md) – WCAG 2.1 AA compliance, high-visibility mode, component specifications

- [Accessibility Theme Tokens](docs/design/accessibility-theme-tokens.md) – Complete design token specifications for standard and high-vis modes



### Knowledge Transfer



**For New System Operators and Board Members:**

- [Knowledge Transfer Checklist](docs/knowledge-transfer-checklist.md) – System overview, operational ownership handoff, routine procedures

- [Architecture Documentation](.codemachine/artifacts/architecture/) – Canonical system architecture and operational rationale

- [Plan Manifest](.codemachine/artifacts/plan_manifest.json) – Traceability from requirements to implementation



**Key Resources:**

- All runbooks reference architecture document anchors (e.g., `04_Operational_Architecture.md#3-12`)

- Video walkthroughs for UI operations (generated screenshots in CI artifacts)

- Regular lunch-and-learn sessions for board transitions (documented in meeting notes)



**Documentation Maintenance:**

- Living documentation reviewed quarterly or after major releases

- Every release requires documentation diff review before merging

- Feedback loops allow residents to request clarifications (2-week update SLA)



**For Technical Handoffs:**

- Comprehensive inline code comments for complex business logic

- Automated test suites verify expected behaviors (>80% backend, >75% frontend coverage)

- Deployment logs maintain historical record of all production changes