Frontend Component Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The frontend architecture of the Lou Gehrig Fan Club (LGFC) project is built on Next.js 15 (App Router) using TypeScript. It follows a strict structural specification known as "V6," which enforces specific component ordering and design invariants to maintain brand consistency across the public site and authenticated FanClub areas.
The system utilizes a hybrid rendering approach: static structural elements are combined with dynamic client-side components that interact with Cloudflare D1 databases for content management. Architecture enforcement is handled via automated repository governance scripts and structural unit tests.
Sources: package.json:44, context.md:8-11, tests/homepage-structure.test.tsx:10-14
Core Structural Layout
The root of the frontend is defined in the top-level layout, which establishes the global shell for all pages. This includes the implementation of global CSS tokens and the standard page header/footer structure.
The RootLayout component wraps all pages in an antialiased body and provides a consistent vertical rhythm using a .topWhitespace div intended to offset content below the header.
Sources: src/app/layout.tsx:17-31, tools/verify_v6_lock.sh:91-95
Design Invariants (V6 Specification)
The project maintains "v6 Lock" invariants verified by shell scripts and Vitest. These invariants ensure specific CSS classes and structural elements remain present to prevent design drift.
| Invariant Category | Required Element/Token | Description |
|---|---|---|
| Color Tokens | --lgfc-blue | Primary brand color used across components. |
| Spacing | .section-gap | Standard vertical spacing between homepage sections. |
| Typography | .title-lgfc | Specialized class for LGFC-branded headings. |
| Layout | .topWhitespace | Mandatory div rendered beneath the header. |
| Header | Non-sticky | The header must not use sticky positioning. |
Sources: tools/verify_v6_lock.sh:78-83, tools/verify_v6_lock.sh:110-112
Component Classification
The architecture divides components into two primary categories based on their lifecycle and data requirements.
Content-Driven Components
These components, such as the FAQSection, fetch data from D1 database endpoints. They often implement optimistic UI updates and fire-and-forget logging for view counts.
Sources: src/app/faq/page.tsx:94-105, src/components/FAQSection.tsx:82-95
Admin Management Components
Admin interfaces located in /admin/** use a "Draft and Publish" workflow. Components like the SectionEditor allow administrators to modify content blocks in D1 before promoting them to the live site.
Sources: src/app/admin/cms/page.tsx:64-98, src/app/admin/content/page.tsx:210-230
Data Flow: Content Management System (CMS)
Content management utilizes a specific sequence for updating the frontend without requiring a code redeploy. CMS blocks are identified by unique keys and associated with specific pages and sections.
Admin pages fetch current block states using an x-admin-token for authorization. Content is stored as raw text/Markdown in the content_blocks table and rendered via dynamic fetch calls in public routes.
Sources: src/app/admin/cms/page.tsx:12-25, src/app/admin/cms/page.tsx:75-80
Homepage Composition
The homepage architecture is strictly governed by a required section order. This is enforced by tests/homepage-structure.test.tsx to ensure the user experience remains consistent with design specifications.
| Order | Section | Content Detail |
|---|---|---|
| 1 | Hero/Banner | Welcome heading (Level 1). |
| 2 | Weekly Matchup | Photo voting section. |
| 3 | Join CTA | Membership call to action. |
| 4 | Social Wall | Elfsight-based social media feed. |
| 5 | Discussions | Recent club member posts preview. |
| 6 | Friends | Partner/Affiliate display. |
| 7 | Milestones | Historical timeline/milestone data. |
| 8 | FAQ | Frequently asked questions preview. |
Sources: tests/homepage-structure.test.tsx:112-126, tests/e2e/homepage-sections.spec.ts:117-128
Navigation and Authentication Shell
The PageShell component acts as a high-level wrapper for various pages, providing standard title and subtitle props. Global navigation is handled by the Header and SiteHeader components, which switch between visitor and member views.
Authentication State Management
Authentication state is managed on the client side, typically utilizing localStorage or sessionStorage for tokens.
- Member Email: Stored in
lgfc_member_email. - Admin Token: Stored in
lgfc_admin_tokenfor access to/adminroutes.
Sources: context.md:20-22, src/app/admin/d1-test/page.tsx:34-40, src/app/admin/content/page.tsx:180-185
Conclusion
The LGFC Frontend Component Architecture is characterized by strict governance over design and structural ordering. By combining a static Next.js App Router framework with a dynamic, token-authorized D1-backed CMS, the system provides a robust platform for managing historical fan content while ensuring that brand invariants remain locked against unauthorized or accidental drift.