Codebase Structure

Overview

Understand the file structure and directory organization to maintain consistency when adding new features, components, or functionality.

Directory Structure

create-reodor-app/
├── app/                    # Next.js App Router - Pages and routes
├── components/             # React components
├── docs/                   # Project documentation
├── hooks/                  # Custom React hooks
├── lib/                    # External service configurations and utilities
├── providers/              # React context providers
├── public/                 # Static assets (images, logos, manifests)
├── schemas/                # Generated Zod schemas (auto-generated)
├── scripts/                # Utility scripts (deployment, setup)
├── seed/                   # Database seeding configuration
├── server/                 # Server actions for data mutations
├── stores/                 # Zustand state management stores
├── supabase/               # Supabase configuration and database
├── transactional/          # React Email templates
├── types/                  # TypeScript type definitions
└── middleware.ts           # Next.js middleware (auth, route protection)

Where to Place New Code

Pages & Routes (app/)

Structure: Next.js App Router with file-based routing

Place here:

• •Page components (page.tsx)
• •Layouts (layout.tsx)
• •Error boundaries (error.tsx, global-error.tsx)
• •Not found pages (not-found.tsx)
• •API routes (api/*/route.ts)
• •Route-specific loading states (loading.tsx)
• •SEO metadata (robots.ts, sitemap.ts, opengraph-image.png)
• •Favicons and app icons

Examples:

• •app/oppgaver/page.tsx - Todos feature page
• •app/auth/sign-in/page.tsx - Sign in page
• •app/api/cron/*/route.ts - Cron job endpoints
• •app/layout.tsx - Root layout with providers

Components (components/)

Structure: Feature-based organization + shared components

Place here:

• •Feature directories (components/[feature]/) - Feature-specific components
  • •Example: components/todos/, components/auth/, components/admin/
• •Shared components - Components used across features
  • •Example: navbar.tsx, footer.tsx, error-boundary.tsx
• •UI library (components/ui/) - shadcn/ui components
• •Specialized UI (components/kibo-ui/) - Kibo UI components
• •Magic UI (components/magicui/) - Magic UI components

Naming: Use kebab-case for directories, PascalCase for component files

Examples:

• •components/todos/todo-form.tsx - Todo form component
• •components/todos/todo-dialog.tsx - Todo dialog wrapper
• •components/auth/auth-form.tsx - Authentication form
• •components/ui/button.tsx - shadcn/ui button component

Server Actions (server/)

Purpose: Type-safe server-side data operations with authentication

Place here:

• •Database CRUD operations
• •Authenticated data mutations
• •Server-side business logic

Naming: [feature].actions.ts

Examples:

• •server/todo.actions.ts - Todo CRUD operations
• •server/profile.actions.ts - Profile management
• •server/admin.actions.ts - Admin operations

Pattern: Individual exported async functions, not default exports

Custom Hooks (hooks/)

Purpose: Reusable React hooks for client-side logic

Place here:

• •Data fetching hooks (TanStack Query)
• •File upload hooks
• •Authentication hooks
• •Form state management hooks
• •UI state hooks (media queries, scroll position, etc.)

Naming: use-[hook-name].ts

Examples:

• •hooks/use-auth.ts - Authentication state
• •hooks/use-upload-todo-attachments.ts - File upload logic
• •hooks/use-media-query.ts - Responsive breakpoint detection

State Management (stores/)

Purpose: Global state with Zustand

Place here:

• •Application-wide state
• •Persisted state (localStorage, sessionStorage)
• •Shared UI state

Naming: [feature]-store.ts or use-[feature]-store.ts

Examples:

• •stores/setup-steps-store.ts - Setup wizard state

Database (supabase/)

Structure:

supabase/
├── schemas/        # Declarative SQL schemas (source of truth)
├── migrations/     # Generated SQL migrations (auto-generated)
└── functions/      # Edge functions (Deno runtime)

Place here:

• •schemas/ - Declarative database schemas, RLS policies, triggers
  • •01-schema.sql - Tables, enums, indexes
  • •02-policies.sql - Row Level Security policies
  • •03-triggers.sql - Database triggers
• •migrations/ - Generated from schemas (DO NOT edit manually)
• •functions/ - Supabase Edge Functions for serverless operations

Workflow:

1. •Edit schema in schemas/
2. •Run bun db:diff <name> to generate migration
3. •Review generated migration in migrations/
4. •Run bun migrate:up to apply

Type Definitions (types/)

Purpose: TypeScript types and interfaces

Place here:

• •database.types.ts - Generated from Supabase (auto-generated, DO NOT edit)
• •index.ts - Custom types, shared filter types, runtime-agnostic types
• •Feature-specific type definitions

Examples:

• •types/database.types.ts - Auto-generated Supabase types
• •types/index.ts - Custom types like BookingFilters, ServiceFilters

Schemas (schemas/)

Purpose: Auto-generated Zod validation schemas

Content:

• •database.schema.ts - Generated from Supabase types (DO NOT edit manually)

Usage: Import schemas for validation in server actions and forms

Generation: Run bun gen:types to regenerate

External Services (lib/)

Purpose: Service configurations and utilities

Place here:

• •Service clients (resend.ts, lib/supabase/client.ts)
• •Service utilities (resend-utils.ts, lib/supabase/storage.ts)
• •Configuration (brand.ts, navigation.ts, permissions.ts)
• •Helper functions (utils.ts - cn(), formatting, etc.)

Structure:

lib/
├── supabase/           # Supabase configuration
│   ├── client.ts       # Browser client
│   ├── server.ts       # Server client
│   └── storage.ts      # Storage utilities
├── brand.ts            # Brand configuration
├── navigation.ts       # Navigation structure
├── utils.ts            # Shared utilities
└── [service].ts        # External service configs

React Providers (providers/)

Purpose: React Context providers for app-wide state

Place here:

• •TanStack Query provider
• •Theme providers
• •Authentication providers
• •Any context providers

Examples:

• •providers/tanstack-query-provider.tsx

Email Templates (transactional/emails)

Purpose: React Email templates for transactional emails

Place here:

• •Email components built with React Email
• •Email-specific utilities

Examples:

• •transactional/emails/welcome.tsx
• •transactional/emails/password-reset.tsx

Documentation (docs/)

Structure:

docs/
├── business/       # Business features and workflows
└── technical/      # Technical implementation details

Place here:

• •business/ - Feature docs, user workflows, business logic
• •technical/ - Architecture, API docs, deployment guides

Examples:

• •docs/technical/google-auth-setup.md
• •docs/technical/railway-deployment.md

Static Assets (public/)

Purpose: Static files served at root path

Place here:

• •Logos and brand assets
• •Web app manifest images
• •Static images referenced by absolute paths
• •Files that need specific public URLs

Structure:

public/
├── logos/                          # Logo variations
├── web-app-manifest-192x192.png   # PWA icons
└── web-app-manifest-512x512.png

Note: Favicons and app icons go in app/ directory, not public/

Utility Scripts (scripts/)

Purpose: Development and deployment automation

Place here:

• •Deployment scripts
• •Setup scripts
• •Database utilities
• •Build automation

Examples:

• •scripts/railway-setup.sh
• •scripts/ensure-transactional-deps-installed.sh

Database Seeding (seed/)

Purpose: Snaplet configuration for database seeding

Place here:

• •Snaplet configuration
• •Seed data scripts

Root-Level Files

• •middleware.ts - Next.js middleware for auth and route protection
• •next.config.ts - Next.js configuration
• •tailwind.config.ts - Tailwind CSS configuration
• •seed.config.ts - Database seeding configuration
• •next-env.d.ts - Next.js TypeScript declarations (auto-generated)

Key Principles

1. •Feature-based organization - Group related files by feature (e.g., components/todos/, server/todo.actions.ts)
2. •Separation of concerns - Keep server logic (server/) separate from client components (components/)
3. •Generated files - Never edit auto-generated files (types/database.types.ts, schemas/database.schema.ts, migrations/)
4. •Naming conventions - Use kebab-case for files, PascalCase for components, camelCase for functions

Common Workflows

Adding a New Feature

1. •Database: Update supabase/schemas/01-schema.sql with new database schema state. Refer to skills/database-schema-extension/SKILL.md for guidance.
2. •Server Actions: Create server/[feature].actions.ts
3. •Components: Create components/[feature]/ directory
4. •Hooks: Add custom hooks to hooks/use-[feature].ts if needed.
5. •Page: Create app/[path-to-feature]/page.tsx. It can be nested as needed.
6. •Types: Custom types go in types/index.ts

Adding a New UI Component

1. •Shared component: components/[name].tsx
2. •Feature component: components/[feature]/[name].tsx
3. •shadcn/ui: Run bunx --bun shadcn@latest add [component] (auto-adds to components/ui/)

Adding Authentication

1. •Server action: Add to server/auth.actions.ts
2. •Middleware: Update route protection in middleware.ts
3. •Components: Add to components/auth/
4. •Hooks: Update hooks/use-auth.ts

Quick Reference