Detailed Frontend Directory Structure

This document is a granulated shard from the main "5-front-end-architecture.md" focusing on "Detailed Frontend Directory Structure".

The BMad DiCaster frontend will adhere to the Next.js App Router conventions and build upon the structure provided by the Vercel/Supabase Next.js App Router template. The monorepo structure defined in the main Architecture Document (docs/architecture.md) already outlines the top-level directories. This section details the frontend-specific organization.

Naming Conventions Adopted:

Directories: kebab-case (e.g., app/(web)/newsletter-list/, app/components/core/)
React Component Files (.tsx): PascalCase.tsx (e.g., NewsletterCard.tsx, PodcastPlayer.tsx). Next.js App Router special files (e.g., page.tsx, layout.tsx, loading.tsx, global-error.tsx, not-found.tsx) retain their conventional lowercase or kebab-case names.
Non-Component TypeScript Files (.ts): Primarily camelCase.ts (e.g., utils.ts, uiSlice.ts). Configuration files (e.g., tailwind.config.ts) and shared type definition files (e.g., api-schemas.ts, domain-models.ts) may retain kebab-case as per common practice or previous agreement.

{project-root}/
├── app/                        # Next.js App Router (Frontend Pages, Layouts, API Routes)
│   ├── (web)/                  # Group for user-facing web pages
│   │   ├── newsletters/        # Route group for newsletter features
│   │   │   ├── [newsletterId]/ # Dynamic route for individual newsletter detail
│   │   │   │   ├── page.tsx    # Newsletter Detail Page component
│   │   │   │   └── loading.tsx # Optional: Loading UI for this route
│   │   │   ├── page.tsx        # Newsletter List Page component
│   │   │   └── layout.tsx      # Optional: Layout specific to /newsletters routes
│   │   ├── layout.tsx          # Root layout for all (web) pages
│   │   └── page.tsx            # Homepage (displays newsletter list)
│   ├── (api)/                  # API route handlers (as defined in main architecture [cite: 82, 127, 130, 133])
│   │   ├── system/
│   │   │   └── ...
│   │   └── webhooks/
│   │       └── ...
│   ├── components/             # Application-specific UI React components (Core Logic)
│   │   ├── core/               # Core, reusable application components
│   │   │   ├── NewsletterCard.tsx
│   │   │   ├── PodcastPlayer.tsx
│   │   │   ├── DownloadButton.tsx
│   │   │   └── BackButton.tsx
│   │   └── layout/             # General layout components
│   │       └── PageWrapper.tsx   # Consistent padding/max-width for pages
│   ├── auth/                   # Auth-related pages and components (from template, MVP frontend is public)
│   ├── login/page.tsx          # Login page (from template, MVP frontend is public)
│   └── global-error.tsx        # Optional: Custom global error UI (Next.js special file)
│   └── not-found.tsx           # Optional: Custom 404 page UI (Next.js special file)
│   ├── components/                 # Shadcn UI components root (as configured by components.json [cite: 92])
│   │   └── ui/                     # Base UI elements from Shadcn (e.g., Button.tsx, Card.tsx)
│   ├── lib/                        # General utility functions for frontend [cite: 86, 309]
│   │   ├── utils.ts                # General utility functions (date formatting, etc.)
│   │   └── hooks/                  # Custom global React hooks
│   │       └── useScreenWidth.ts   # Example custom hook
│   ├── store/                      # Zustand state management
│   │   ├── index.ts                # Main store setup/export (can be store.ts or index.ts)
│   │   └── slices/                 # Individual state slices
│   │       └── podcastPlayerSlice.ts # State for the podcast player
│   ├── public/                     # Static assets (images, favicon, etc.) [cite: 89]
│   │   └── logo.svg                # Application logo (to be provided [cite: 379])
│   ├── shared/                     # Shared code/types between frontend and Supabase functions [cite: 89, 97]
│   │   └── types/
│   │       ├── api-schemas.ts      # Zod schemas for API req/res
│   │       └── domain-models.ts    # Core entity types (HNPost, Newsletter, etc. from main arch)
│   ├── styles/                     # Global styles [cite: 90]
│   │   └── globals.css             # Tailwind base styles, custom global styles
│   ├── utils/                      # Root utilities (from template [cite: 91])
│   │   └── supabase/               # Supabase helper functions FOR FRONTEND (from template [cite: 92, 309])
│   │       ├── client.ts           # Client-side Supabase client
│   │       ├── middleware.ts       # Logic for Next.js middleware (Supabase auth [cite: 92, 311])
│   │       └── server.ts           # Server-side Supabase client
│   ├── tailwind.config.ts          # Tailwind CSS configuration [cite: 93]
│   └── tsconfig.json               # TypeScript configuration (includes path aliases like @/* [cite: 101])

Notes on Frontend Structure:

app/(web)/: Route group for user-facing pages.
- newsletters/page.tsx: Server Component for listing newsletters. [cite: 375, 573]
- newsletters/[newsletterId]/page.tsx: Server Component for displaying a single newsletter. [cite: 376, 576]
app/components/core/: Houses application-specific React components like NewsletterCard.tsx, PodcastPlayer.tsx, DownloadButton.tsx, BackButton.tsx (identified in ux-ui-spec.txt). Components follow PascalCase.tsx.
app/components/layout/: For structural layout components, e.g., PageWrapper.tsx. Components follow PascalCase.tsx.
components/ui/: Standard directory for Shadcn UI components (e.g., Button.tsx, Card.tsx).
lib/hooks/: Custom React hooks (e.g., useScreenWidth.ts), files follow camelCase.ts.
store/slices/: Zustand state slices. podcastPlayerSlice.ts for podcast player state. Files follow camelCase.ts.
shared/types/: Type definitions. api-schemas.ts and domain-models.ts use kebab-case.ts.
utils/supabase/: Template-provided Supabase clients. Files follow camelCase.ts.
Path Aliases: tsconfig.json uses @/* aliases. [cite: 98, 101]

6.6 KiB Raw Blame History

Detailed Frontend Directory Structure

Notes on Frontend Structure:

6.6 KiB

Raw Blame History