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

Type	Location	Example
Page	app/[route]/page.tsx	app/oppgaver/page.tsx
Server Action	server/[feature].actions.ts	server/todo.actions.ts
Component	components/[feature]/[name].tsx	components/todos/todo-form.tsx
Hook	hooks/use-[name].ts	hooks/use-auth.ts
Store	stores/[name]-store.ts	stores/setup-steps-store.ts
Database Schema	supabase/schemas/01-schema.sql	Table definitions
Email Template	transactional/[name]-email.tsx	transactional/welcome-email.tsx
Util Function	lib/utils.ts or lib/[service]-utils.ts	lib/resend-utils.ts
Type	types/index.ts	Custom types
API Route	app/api/[route]/route.ts	app/api/cron/demo/route.ts