System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Lou Gehrig Fan Club (LGFC) platform is a full-stack web application designed for high availability and strict design compliance. It utilizes a modern web stack optimized for the Cloudflare ecosystem, focusing on static site generation (SSG) with dynamic administrative capabilities.
The architecture is built around a Next.js (App Router) frontend deployed to Cloudflare Pages, using Cloudflare D1 as a serverless relational database for content management and Backblaze B2 for media asset storage.
Sources: context.md:1-25, package.json:1-40
Core Technology Stack
The system's foundation relies on a combination of static hosting and serverless compute.
| Component | Technology | Role |
|---|---|---|
| Framework | Next.js 15 (App Router) | Frontend and API Route handling |
| Runtime | Node.js 22 | Development and build environment |
| Deployment | Cloudflare Pages | Hosting and Static Export |
| Database | Cloudflare D1 | Content, FAQ, and membership data |
| Assets | Backblaze B2 | External storage for images and media |
| Language | TypeScript | Type-safe application logic |
Sources: context.md:14-20, package.json:96-105
Component Architecture and Data Flow
The application differentiates between public-facing static content and administrative dynamic management. The administrative layer interacts with Cloudflare D1 to manage site content via a draft-and-publish workflow.
Content Management System (CMS) Flow
The CMS utilizes a structured workflow where content is first saved as a draft in the content_blocks table before being promoted to a published state.
The diagram shows the transition of content from an administrative draft to a public-facing published block.
Sources: src/app/admin/cms/page.tsx:64-105, src/app/admin/content/page.tsx:84-140
Administrative Modules
The admin area provides specialized interfaces for different content types:
- CMS Blocks: Generic management of the
content_blockstable with Markdown support. - Content Editor: Section-based editing for specific site slugs (e.g.,
/,/about). - Fundraiser Preview: A gated area for building and validating homepage campaign spotlights before public enabling.
Sources: src/app/admin/cms/page.tsx:135-225, src/app/admin/content/page.tsx:150-200, src/app/admin/fundraiser-preview/page.tsx:154-200
Data Structures and Schema
The application logic revolves around several key data structures used for content synchronization and state management.
CMS Content Block
The Block type is the primary structure for managed content.
type Block = {
key: string;
page: string;
section: string;
title: string;
body_md: string;
status: 'draft' | 'published';
published_body_md: string | null;
version: number;
updated_at: string;
published_at: string | null;
updated_by: string;
};
Sources: src/app/admin/cms/page.tsx:7-19
API Response Handling
Administrative components implement a "safe" JSON parsing strategy to ensure the UI renders correctly even if API routes are not yet available (e.g., during partial builds).
Sources: src/app/admin/content/page.tsx:34-52
Infrastructure and Deployment
The system is hosted on Cloudflare Pages using a static export build strategy.
DevOps and Snapshotting
A specialized snapshot system is implemented to provide reproducible recovery of the Cloudflare Pages project configuration. The cf_pages_snapshot.sh script automates the capture of project metadata, custom domains, and deployment records.
The snapshot process captures read-only metadata for audit and disaster recovery purposes.
Sources: scripts/cf_pages_snapshot.sh:11-85, snapshots/cloudflare/README.md:1-25
Governance and Verification
The architecture enforces strict design and structural invariants through automated testing and locking scripts.
- Homepage Lock: A Vitest-based "Drift Guard" ensures sections (Hero, Weekly Matchup, Social Wall, etc.) remain in the approved V6 specification order.
- V6 Lock Verification: A bash-based verifier (
tools/verify_v6_lock.sh) audits the repository for CSS tokens, non-sticky headers, and required UI components.
Sources: tests/homepage-structure.test.tsx:13-130, tools/verify_v6_lock.sh:75-200
Conclusion
The LGFC System Architecture combines the performance benefits of a static Next.js frontend with the flexibility of a serverless D1-backed CMS. Its design is heavily influenced by strict governance requirements, utilizing automated snapshots and structural "lock" tests to maintain visual and functional integrity across deployments.