82 lines
6.6 KiB
Markdown
82 lines
6.6 KiB
Markdown
# 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.
|
|
|
|
```plaintext
|
|
{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]
|