BMAD-METHOD/BETA-V3/v3-demos/full-stack-app-demo/10-sharded-docs/front-end-architecture.md

BMad DiCaster Frontend Architecture Document

Table of Contents

• Introduction
• Overall Frontend Philosophy & Patterns
• Detailed Frontend Directory Structure
• Component Breakdown & Implementation Details
  • Component Naming & Organization
  • Template for Component Specification
• State Management In-Depth
  • Chosen Solution
  • Rationale
  • Store Structure / Slices
  • Key Selectors
  • Key Actions / Reducers / Thunks
• API Interaction Layer
  • Client/Service Structure
  • Error Handling & Retries (Frontend)
• Routing Strategy
  • Routing Library
  • Route Definitions
  • Route Guards / Protection
• Build, Bundling, and Deployment
  • Build Process & Scripts
  • Key Bundling Optimizations
  • Deployment to CDN/Hosting
• Frontend Testing Strategy
  • Link to Main Testing Strategy
  • Component Testing
  • UI Integration/Flow Testing
  • End-to-End UI Testing Tools & Scope
• Accessibility (AX) Implementation Details
• Performance Considerations
• Change Log

Introduction

This document details the technical architecture specifically for the frontend of BMad DiCaster. It complements the main BMad DiCaster Architecture Document and the UI/UX Specification. The goal is to provide a clear blueprint for frontend development, ensuring consistency, maintainability, and alignment with the overall system design and user experience goals.

• Link to Main Architecture Document: docs/architecture.md (Note: The overall system architecture, including Monorepo/Polyrepo decisions and backend structure, will influence frontend choices, especially around shared code or API interaction patterns.)
• Link to UI/UX Specification: docs/ui-ux-spec.txt
• Link to Primary Design Files (Figma, Sketch, etc.): N/A (Low-fidelity wireframes described in docs/ui-ux-spec.txt; detailed mockups to be created during development)
• Link to Deployed Storybook / Component Showcase (if applicable): N/A (To be developed)

Overall Frontend Philosophy & Patterns

Key aspects of this section have been moved to dedicated documents:

• For styling approach, theme customization, and visual design: See Frontend Style Guide
• For core framework choices, component architecture, data flow, and general coding standards: See Frontend Coding Standards & Accessibility

Detailed Frontend Directory Structure

This section has been moved to a dedicated document: Detailed Frontend Directory Structure

Component Breakdown & Implementation Details

This section has been moved to a dedicated document: Component Breakdown & Implementation Details

State Management In-Depth

This section has been moved to a dedicated document: State Management In-Depth

API Interaction Layer

This section has been moved to a dedicated document: API Interaction Layer

Routing Strategy

This section has been moved to a dedicated document: Routing Strategy

Build, Bundling, and Deployment

Details align with the Vercel platform and Next.js capabilities.

Build Process & Scripts

• Key Build Scripts:
  • npm run dev: Starts Next.js local development server.
  • npm run build: Generates an optimized production build of the Next.js application. (Script from package.json)
  • npm run start: Starts the Next.js production server after a build.
• Environment Variables Handling during Build:
  • Client-side variables must be prefixed with NEXT_PUBLIC_ (e.g., NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY).
  • Server-side variables (used in Server Components, Server Actions, Route Handlers) are accessed directly via process.env.
  • Environment variables are managed in Vercel project settings for different environments (Production, Preview, Development). Local development uses .env.local.

Key Bundling Optimizations

• Code Splitting: Next.js App Router automatically performs route-based code splitting. Dynamic imports (next/dynamic) can be used for further component-level code splitting if needed.
• Tree Shaking: Ensured by Next.js's Webpack configuration during the production build process.
• Lazy Loading: Next.js handles lazy loading of route segments by default. Images (next/image) are optimized and can be lazy-loaded.
• Minification & Compression: Handled automatically by Next.js during npm run build (JavaScript, CSS minification; Gzip/Brotli compression often handled by Vercel).

Deployment to CDN/Hosting

• Target Platform: Vercel (as per architecture.txt)
• Deployment Trigger: Automatic deployments via Vercel's Git integration (GitHub) on pushes/merges to specified branches (e.g., main for production, PR branches for previews). (Aligned with architecture.txt)
• Asset Caching Strategy: Vercel's Edge Network handles CDN caching for static assets and Server Component payloads. Cache-control headers will be configured according to Next.js defaults and can be customized if necessary (e.g., for public/ assets).

Frontend Testing Strategy

This section has been moved to a dedicated document: Frontend Testing Strategy

Accessibility (AX) Implementation Details

This section has been moved to a dedicated document: Frontend Coding Standards & Accessibility

Performance Considerations

[cite_start] The goal is a fast-loading and responsive user experience. [cite: 360, 565]

• Image Optimization:
  • Use next/image for automatic image optimization (resizing, WebP format where supported, lazy loading by default).
• Code Splitting & Lazy Loading:
  • Next.js App Router handles route-based code splitting.
  • next/dynamic for client-side lazy loading of components that are not immediately visible or are heavy.
• Minimizing Re-renders (React):
  • Judicious use of React.memo for components that render frequently with the same props.
  • Optimizing Zustand selectors if complex derived state is introduced (though direct access is often sufficient).
  • Ensuring stable prop references where possible.
• Debouncing/Throttling: Not anticipated for MVP features, but will be considered for future interactive elements like search inputs.
• Virtualization: Not anticipated for MVP given the limited number of items (e.g., 30 newsletters per day). If lists become very long in the future, virtualization libraries like TanStack Virtual will be considered.
• Caching Strategies (Client-Side):
  • Leverage Next.js's built-in caching for Server Component payloads and static assets via Vercel's Edge Network.
  • Browser caching for static assets (public/ folder) will use default optimal headers set by Vercel.
• Performance Monitoring Tools:
  • Browser DevTools (Performance tab, Lighthouse).
  • Vercel Analytics (if enabled) for real-user monitoring.
  • WebPageTest for detailed performance analysis.
• Bundle Size Analysis: Use tools like @next/bundle-analyzer to inspect production bundles and identify opportunities for optimization if bundle sizes become a concern.

Change Log

Date	Version	Description	Author
2025-05-13	0.1	Initial draft of frontend architecture document.	4-design-arch (AI)