Project Structure
Last updated on 2026-09-03
The kit follows Next.js App Router conventions with a clean separation between frontend components, backend logic, and database infrastructure.
Top-Level Structure
blog-fullstack/
├── app/ # Next.js routes
├── components/ # React components (3-tier hierarchy)
├── data/ # Static data (navigation, sidebar items)
├── hooks/ # Custom React hooks
├── lib/ # Utilities, Supabase clients, Server Actions
├── supabase/ # Database migrations and seed data
├── types/ # TypeScript type definitions
├── public/ # Static assets
├── middleware.ts # Auth middleware for route protection
└── .env.example # Environment variable template
Route Groups
The app/ directory uses Next.js route groups for layout separation:
app/
├── (blog)/ # Public blog pages
│ ├── layout.tsx # BlogHeader + BlogFooter
│ ├── page.tsx # Blog homepage with featured posts
│ ├── about/
│ │ └── page.tsx # About page
│ ├── authors/
│ │ └── [slug]/
│ │ └── page.tsx # Author profile with their posts
│ ├── categories/
│ │ ├── page.tsx # All categories listing
│ │ └── [slug]/
│ │ └── page.tsx # Category detail with posts
│ ├── newsletter/
│ │ └── page.tsx # Newsletter archive
│ ├── posts/
│ │ └── [slug]/
│ │ └── page.tsx # Article detail with comments and view counting
│ ├── search/
│ │ └── page.tsx # Search with filtering
│ ├── tags/
│ │ └── [slug]/
│ │ └── page.tsx # Tag detail with posts
│ ├── rss/
│ │ └── page.tsx # RSS feed
│ └── sitemap/
│ └── page.tsx # Sitemap preview
├── (admin)/ # Admin CMS pages (protected)
│ ├── layout.tsx # AdminSidebar + AdminHeader
│ └── admin/
│ ├── page.tsx # Dashboard with stats from database aggregates
│ ├── posts/
│ │ ├── page.tsx # Posts list with draft/published/scheduled tabs
│ │ ├── new/
│ │ │ └── page.tsx # New post editor
│ │ └── [id]/
│ │ └── edit/
│ │ └── page.tsx # Edit post
│ ├── analytics/
│ │ └── page.tsx # Pageview trends, top posts, subscriber growth
│ ├── comments/
│ │ └── page.tsx # Comment moderation queue
│ ├── authors/
│ │ └── page.tsx # Author management
│ ├── tags/
│ │ └── page.tsx # Tag management
│ ├── categories/
│ │ └── page.tsx # Category management
│ ├── media/
│ │ └── page.tsx # Media library with Supabase Storage
│ ├── subscribers/
│ │ └── page.tsx # Subscriber list with search and export
│ ├── scheduled/
│ │ └── page.tsx # Scheduled posts queue
│ └── settings/
│ └── page.tsx # Site settings
├── (auth)/ # Authentication pages
│ ├── layout.tsx # Centered card layout
│ ├── login/
│ │ └── page.tsx # Login with email and OAuth
│ ├── register/
│ │ └── page.tsx # Registration
│ ├── forgot-password/
│ │ └── page.tsx # Password reset
│ └── auth/
│ └── callback/
│ └── route.ts # OAuth callback handler
└── not-found.tsx # 404 page
Component Hierarchy
Components follow a 3-tier system:
components/
├── ui/ # Tier 1: shadcn/ui primitives (never modified)
│ ├── button.tsx
│ ├── card.tsx
│ ├── dialog.tsx
│ ├── table.tsx
│ ├── tabs.tsx
│ ├── textarea.tsx
│ └── ...
├── blog/ # Tier 2: Blog composites
│ ├── post-card.tsx
│ ├── post-hero.tsx
│ ├── post-body.tsx
│ ├── post-toc.tsx
│ ├── post-navigation.tsx
│ ├── share-buttons.tsx
│ ├── author-card.tsx
│ ├── category-tabs.tsx
│ ├── newsletter-form.tsx
│ ├── reading-progress.tsx
│ ├── search-results.tsx
│ ├── comment-card.tsx
│ ├── comment-form.tsx
│ └── ...
├── admin/ # Tier 2: Admin CMS composites
│ ├── stats-card.tsx
│ ├── status-badge.tsx
│ ├── activity-timeline.tsx
│ ├── post-editor.tsx
│ ├── post-form.tsx
│ ├── media-grid.tsx
│ ├── media-upload.tsx
│ ├── comment-moderation.tsx
│ ├── subscriber-table.tsx
│ └── ...
├── charts/ # Tier 2: Chart composites
│ ├── pageview-chart.tsx
│ ├── subscriber-growth-chart.tsx
│ ├── post-views-chart.tsx
│ ├── traffic-source-chart.tsx
│ └── ...
└── layout/ # Tier 2: Layout components
├── blog-header.tsx
├── blog-footer.tsx
├── admin-sidebar.tsx
├── admin-header.tsx
├── theme-toggle.tsx
├── skip-link.tsx
└── ...
Backend Infrastructure
lib/
├── supabase/
│ ├── client.ts # Browser Supabase client
│ ├── server.ts # Server Supabase client (reads cookies)
│ └── admin.ts # Service-role client (bypasses RLS)
├── actions/ # Next.js Server Actions
│ ├── auth.ts # Login, register, logout, password reset
│ ├── posts.ts # Post CRUD with draft/published/scheduled workflow
│ ├── categories.ts # Category CRUD
│ ├── tags.ts # Tag CRUD and post tagging
│ ├── comments.ts # Public submission and moderation (approve/reject/spam)
│ ├── media.ts # Upload to Supabase Storage, delete, update metadata
│ ├── subscribers.ts # Newsletter signup, unsubscribe, export
│ ├── authors.ts # Author profile management and role updates
│ ├── analytics.ts # Aggregate queries for dashboard and analytics page
│ └── settings.ts # Site settings management
├── queries.ts # Supabase query helpers and data mappers
├── schemas.ts # Zod validation schemas
└── utils.ts # Formatting, date helpers, reading time calculation
Database Files
supabase/
├── migrations/
│ ├── 001_schema.sql # 11 tables with relationships and indexes
│ ├── 002_rls.sql # Public read and role-based write RLS policies
│ ├── 003_triggers.sql # Auto profile creation, updated_at, view counting, reading time
│ └── 004_storage.sql # blog-assets bucket for images and media
└── seed.sql # 15 posts, 5 authors, 6 categories, 18 tags, 20 comments, 18 subscribers, 30 days pageviews
Key Files
| File | Purpose |
|---|---|
middleware.ts |
Protects all admin routes, redirects unauthenticated users to /login |
hooks/use-user.ts |
Client hook for current user session and role |
types/database.ts |
Generated Supabase database types |
types/index.ts |
Application-level TypeScript interfaces |
data/static.ts |
Navigation items, sidebar links (non-DB data) |
lib/queries.ts |
Reusable Supabase query helpers for posts, categories, tags, and authors |
lib/schemas.ts |
Zod schemas for post, comment, subscriber, and settings forms |