Technology Stack Documentation

Introduction: What Free For Charity Does

Free For Charity is a nonprofit technology initiative that delivers free, secure, and scalable websites for charities. We act as a general contractor for technology, integrating best‑in‑class platforms—GitHub, Microsoft 365, and Cloudflare—to build, host, secure, and operate modern static sites.

Who this page is for: nonprofit partners, developers, auditors, and admins who need a transparent, detailed view of how we run, secure, and support the platform.

Our Priorities

• Speed & simplicity — Static‑by‑default React + Next.js exports, globally cached, minimal moving parts
• Security by design — MFA, automated scanning, least‑privilege access, auditable workflows
• Compliance & privacy — U.S. privacy laws (CCPA/CPRA) first, then GDPR; consent‑gated analytics via custom banner + secure cookies + Zaraz
• AI‑powered productivity — GitHub Copilot Pro (Agent Mode) & Microsoft Copilot for Microsoft 365
• Resilience — Verified backups to OneDrive for Business with automated restore drills

Charities retain full ownership of their content and brand. Free For Charity coordinates providers, safeguards the platform, and supports operations.

At‑a‑Glance

This is the single source of truth for our stack, operations, and governance.

1) Hosting & Version Control

• GitHub Pro Pages — Static hosting for nonprofit sites (HTTPS, custom domains)
• GitHub Actions — CI/CD for build, test, deploy, security, backups
• GitHub Packages — Package/dependency hosting (as needed)
• GitHub Pro (Nonprofit) — Org/repo plan benefits and Actions minutes

Repository standards

• Node: 20 LTS · Package manager: pnpm (lockfile committed)
• Branch protection: required checks on main, linear history, no force pushes
• Commits: Conventional Commits (feat/fix/docs/refactor/etc.)
• Versioning: Semantic Versioning (tags on releases)
• Labels: shared taxonomy (see §7)
• Templates: Issue/PR templates, CODEOWNERS (see §7)

2) Development Framework & UI

Performance, accessibility & SEO budgets

CI enforced:

• Lighthouse thresholds: Perf ≥ 90, A11y ≥ 95, Best Practices ≥ 95, SEO ≥ 95 (build fails if below)
• Images: optimized at build; Cloudflare edge compression; (optional) Cloudflare Images/Polish
• SEO: sitemap.xml, robots.txt, canonical tags

3) AI Assistance

3.1 Vibe Coding

• GitHub Copilot Pro (Agent Mode) (licensed)
• Copilot Chat (VS Code)
• GitHub Codespaces
• VS Code · Dev Containers
• GitHub CLI · Markdownlint
• GitHub Agent assigned to Issues for triage/summaries/proposed fixes

Acceptable use & privacy: No secrets in prompts; review outputs; adhere to repo policies and license compliance.

3.2 Vibe Working

• Microsoft Copilot for Microsoft 365 (licensed)
• Outlook · Teams (Intelligent Recap) · Word · Excel · PowerPoint · Planner · Whiteboard · Power Automate

Copilot outputs are aids, not authoritative policy/legal advice; human review required.

4) Security & Edge Performance

4.1 GitHub‑native security (Public repos)

• Dependabot · Secret Scanning · Push Protection · Code Scanning (CodeQL) · Dependency Review

Secrets policy & supply chain

• Secrets in GitHub Secrets only; rotate every 90 days; least‑privilege tokens
• Threat model: static site (no server) → primary risks: npm supply chain, secret leakage, client script injection
• Mitigations: CI scanners, branch protection, CSP (see Appendix C), consent‑gated analytics

4.2 Cloudflare edge (security & performance)

• Security: WAF, DDoS protection, SSL/TLS Full (strict), DNSSEC
• Performance: CDN caching, Brotli compression, HTTP/2/3, Page Rules/redirects
• Headers (managed at Cloudflare): CSP, HSTS, Referrer‑Policy, Permissions‑Policy (see Appendix C for recommended values)

5) Compliance & Privacy (U.S. first, then EU)

Regulatory scope

• CCPA/CPRA & U.S. state laws: disclosure, opt‑out ("Do Not Sell/Share"), consent before analytics
• GDPR (EU): explicit, revocable consent before analytics; records of consent

Consent enforcement (GitHub Pages‑compatible)

• Custom blocking banner (Accept/Decline); consent stored in Secure, SameSite cookie or localStorage
• Accept → Cloudflare Zaraz loads Microsoft Clarity
• Decline → analytics blocked; essential site only
• Revocation: "Privacy & Cookies" (or "Do Not Sell/Share") page clears consent cookie and reloads
• Retention: consent cookie 6 months; CI artifacts 90 days; Clarity retention per Microsoft defaults (confirm in tenant)

Privacy checks in CI/CD

Lighthouse CI, HTMLHint, custom script check ensure no analytics loads pre‑consent

Third‑party processors

GitHub, Microsoft (Clarity, M365), Cloudflare (Zaraz, CDN); DPAs/privacy pages linked in Appendix C notes

6) Backup & Disaster Recovery

• GitHub Actions — scheduled backups, verification, alerts
• GitHub Releases/Artifacts — immutable build snapshots
• OneDrive for Business — off‑site backup destination

7) Project Management

• Microsoft Planner — Kanban per charity
• GitHub Projects — roadmaps/boards (Issues/PRs)
• GitHub Issues — backlog, bugs, features
• GitHub Milestones — releases/quarters
• Issue/PR Templates · CODEOWNERS · actions/labeler · github/issue‑metrics
• Power Automate — sync Issues ↔ Planner; Teams notifications
• GitHub for Microsoft Teams app — PR/Issue/Actions notifications
• GitHub Agent (AI) — triage/summarize/propose fixes

Label taxonomy

Types: type/bug, type/feature, type/docs, type/chore

Priority: prio/p0 (critical), p1, p2, p3

Contribution

Public repos accept PRs; see CONTRIBUTING.md & Code of Conduct in each repo

8) Monitoring & Observability

• Uptime: UptimeRobot (or GitHub Status Pages) for public endpoint checks
• Link integrity: lycheeverse/lychee in CI to catch broken links
• Error tracking (optional): Sentry for client‑side JS (respect consent)
• Performance telemetry: Lighthouse CI trends per commit/PR

Appendix B — GitHub Security & Quality Workflows

• Dependabot config (.github/dependabot.yml)
• CodeQL workflow (.github/workflows/codeql-analysis.yml)
• Security & Quality workflow (.github/workflows/security-and-quality.yml)
  • ESLint · Stylelint · Prettier check · tests · Lighthouse CI · HTMLHint
  • Link check: lycheeverse/lychee
  • (Optional) A11y tests: axe-core/jest-axe on key pages

Full YAML examples are included here; integrate thresholds and fail criteria as shown.

# (Abridged) Add to security-and-quality.yml
- name: Link check
  run: npx lychee --exclude-mail --no-progress --quiet ./out

Appendix C — Compliance & Privacy Snippets (Consent & Headers)

C1. Custom Consent Banner (blocking) — HTML/JS

Implements Accept/Decline; sets Secure, SameSite cookie; triggers Zaraz on accept.

C2. Cloudflare Zaraz — Conditional Firing (Consent Cookie)

Reads consent=analytics-accepted and fires Microsoft Clarity.

{
  "variables": [{
    "name": "consent",
    "type": "cookie",
    "key": "consent"
  }],
  "triggers": [{
    "name": "analytics-consent",
    "conditions": [{
      "variable": "consent",
      "operator": "equals",
      "value": "analytics-accepted"
    }]
  }],
  "tags": [{
    "name": "Microsoft Clarity",
    "trigger": "analytics-consent",
    "type": "script",
    "src": "https://www.clarity.ms/tag/CLARITY_PROJECT_ID"
  }]
}

C3. CI Check — Block hardcoded Clarity

! grep -R "https://www.clarity.ms/tag" -n ./out || (echo "Clarity must be injected via Zaraz post‑consent." && exit 1)

C4. Security Headers (Cloudflare)

C5. Revocation & Do‑Not‑Sell/Share

Route: /privacy and /do-not-sell-or-share

Action: clear consent cookie, reload, show state = "declined"

Appendix D — Backup & DR Workflows

• Build → Manifest → Zip → Release (Next.js out/ + checksums)
• Off‑site sync to OneDrive (rclone)
• Integrity verification (download + checksum)
• Alert on failure (GitHub Issue + optional Teams webhook)
• Retention: Releases 30 days; OneDrive zips 90 days

YAML examples included (from prior version). Add weekly restore drill and log result in a GitHub Issue template.

Appendix E — Changelog