Documentation Center

README.md

The primary documentation for this repository. Covers deployment status, responsive design, analytics setup, testing, code quality standards, and commit signing requirements. This is your starting point for understanding the entire project.

Audience: Everyone - Developers, Administrators, New Contributors

QUICK_START.md

A 5-minute setup guide for enabling automatic commit signing using the Free For Charity GPG key. Includes step-by-step instructions for adding the public key to GitHub and configuring repository secrets.

Audience: Repository Administrators, New Developers

/legacy-wordpress-administration/wordpress-online-impacts-onboarding

End-to-end workflow for bringing a new charity online: validation, accounts, hosting, and the service-delivery stages. Start here when a new charity is approved.

Audience: Global Admins, Onboarding volunteers

/legacy-wordpress-administration/wordpress-escalation-runbook

Consolidated escalation paths for when a site won’t load, email breaks, or a domain may have lapsed — who to contact and in what order.

Audience: Global Admins, Maintainers

docs/dns-cutover-runbook.md

The step-by-step procedure and redirect-verification script for cutting a domain over to the static stack. Use alongside the cutover site plan.

Audience: Global Admins, DevOps

SECURITY.md

How FFC handles security reports and Dependabot/CodeQL alerts, the disclosure policy, and who to contact. Read before acting on any security finding.

Audience: Global Admins, Security Team

docs/site-owner-repo-config.md

The required repository settings (auto-merge + branch protection + write access) so a charity owner’s "approve → it publishes" flow works.

Audience: Global Admins

DEPLOYMENT.md

Comprehensive guide for deploying this Next.js site to GitHub Pages. Covers Next.js configuration for static export, custom domain setup, GitHub Actions workflow, build output structure, and troubleshooting common deployment issues.

Audience: DevOps Engineers, Repository Administrators

.github/workflows/README.md

Documentation for the GitHub Actions workflows: CI (continuous integration with testing and linting), CodeQL Analysis (automated security scanning), Deploy (production deployment), and the scheduled data feeds (sites list, CI status, domain expiry, volunteer hours).

Audience: DevOps Engineers, Developers

docs/data-contracts.md

The committed-JSON contracts behind the live dashboards (CI status, domain expiry, volunteer hours): what each feed contains, how it refreshes, and how the UI degrades gracefully when data is stale.

Audience: Developers, Global Admins

CODE_QUALITY.md

Comprehensive overview of code quality standards including ESLint configuration, TypeScript type safety, testing framework (Jest + React Testing Library), security scanning, and recommendations for enhancements. Essential reading for maintaining high code quality.

Audience: Developers, Code Reviewers, Quality Assurance

TEST_CASES.md

Detailed documentation of all test cases including build output validation, GitHub Pages configuration, SEO metadata, route generation, and configuration validation. Explains the test framework, coverage goals, and maintenance procedures.

Audience: Developers, Quality Assurance, Testers

/testing

Comprehensive public-facing test documentation covering every test suite, their purposes, what they test, why they are important, and how to verify them manually. Includes a live CI status badge.

Audience: All Users - Developers, QA Testers, Administrators, Auditors

SECURITY.md

How to report a vulnerability, the disclosure policy, and how FFC triages Dependabot and CodeQL alerts.

Audience: Everyone, Security Team

GPG_SIGNING.md

Technical documentation explaining why GPG signatures are required, how GitHub verifies signatures, and solutions for enabling commit signing including repository settings, GitHub Apps, bot configuration, and workflow automation.

Audience: Repository Administrators, Security Team, Developers

docs/security-controls.md

The enforced security controls (MFA, Conditional Access) and the documented gaps, with SSO status. Reference when answering a security questionnaire.

Audience: Global Admins, Security Team, Auditors

RESPONSIVE_DESIGN.md

Complete responsive design documentation covering Tailwind CSS breakpoints, navigation behavior across devices, expected behavior at different screen sizes, a troubleshooting guide for cache and CSS loading issues, and testing/verification results.

Audience: Frontend Developers, Designers, QA Testers

/sites-list

Master list of all managed domains with health checks, the domain-expiration tracker, and per-row quick links. Integrates WHMCS, Cloudflare, and WPMUDEV data, refreshed by scheduled workflows.

Audience: All Users - Administrators, Site Managers, Auditors

.github/workflows/update-sites-data.yml

Automated weekly workflow that fetches the published sites list (CSV + JSON) from FreeForCharity/FFC-Cloudflare-Automation — where the WHMCS/Cloudflare/WPMUDEV merge, health checks, and scoring run — and opens a pull request to sync it here.

Audience: Repository Administrators, DevOps Engineers, Site Managers

docs/archived/README.md

Documentation that has been archived (consolidated GPG/auto-signing guides, responsive testing results, and completed implementation issues). Preserved for historical reference and audit purposes.

Audience: Repository Administrators, Auditors, Historical Reference