Directory Structure

Comprehensive directory organization, file structure patterns, and code organization principles.

Directory Structure

This section covers the comprehensive directory organization, file naming conventions, and structural patterns used throughout the application.

Root Level Organization

Project Root Structure

smart-shelf/
├── app/                          # Next.js App Router (main application)
├── components/                   # Reusable React components
├── lib/                         # Utility libraries and shared logic
├── hooks/                       # Custom React hooks
├── types/                       # TypeScript type definitions
├── public/                      # Static assets and files
├── styles/                      # Global styles and Tailwind configurations
├── test/                        # Test utilities and configurations
├── docs/                        # Project documentation
├── scripts/                     # Build and deployment scripts
├── middleware.ts                # Next.js middleware
├── next.config.js               # Next.js configuration
├── tailwind.config.js           # Tailwind CSS configuration
├── tsconfig.json                # TypeScript configuration
├── package.json                 # Dependencies and scripts
├── .env.local                   # Environment variables (local)
├── .env.example                 # Environment variables template
├── .gitignore                   # Git ignore patterns
└── README.md                    # Project documentation

Core Directory Functions

/app - Next.js App Router

  • Purpose: Main application routes and pages
  • Pattern: File-based routing with App Router conventions
  • Organization: Feature-based routing with nested layouts

/components - Reusable Components

  • Purpose: Shared UI components across the application
  • Pattern: Atomic design principles with feature grouping
  • Organization: Hierarchical structure from atoms to organisms

/lib - Shared Libraries

  • Purpose: Utility functions, services, and shared business logic
  • Pattern: Feature-based modules with clear interfaces
  • Organization: Domain-driven structure with utilities

/hooks - Custom React Hooks

  • Purpose: Reusable stateful logic and side effects
  • Pattern: Single responsibility hooks with TypeScript
  • Organization: Feature-based grouping with shared utilities

/types - TypeScript Definitions

  • Purpose: Shared type definitions and interfaces
  • Pattern: Domain-driven type organization
  • Organization: Database, API, and component type separation

App Router Structure

Protected Application Routes

app/
├── (app)/                       # Route group for authenticated pages
│   ├── layout.tsx               # Protected layout with navigation
│   ├── loading.tsx              # Global loading component
│   ├── error.tsx                # Global error boundary
│   ├── not-found.tsx            # 404 page for protected routes
│   │
│   ├── dashboard/               # Main dashboard
│   │   ├── page.tsx             # Dashboard overview
│   │   ├── loading.tsx          # Dashboard loading state
│   │   ├── error.tsx            # Dashboard error boundary
│   │   └── components/          # Dashboard-specific components
│   │       ├── stats-cards.tsx
│   │       ├── recent-orders.tsx
│   │       ├── inventory-alerts.tsx
│   │       └── performance-chart.tsx
│   │
│   ├── inventory/               # Inventory management
│   │   ├── page.tsx             # Inventory overview
│   │   ├── layout.tsx           # Inventory section layout
│   │   ├── loading.tsx          # Inventory loading states
│   │   ├── adjustments/         # Stock adjustments
│   │   │   ├── page.tsx         # Adjustments list
│   │   │   ├── new/             # Create adjustment
│   │   │   │   ├── page.tsx
│   │   │   │   └── components/
│   │   │   └── [id]/            # Adjustment details
│   │   │       ├── page.tsx
│   │   │       ├── edit/
│   │   │       └── components/
│   │   ├── movements/           # Stock movements
│   │   │   ├── page.tsx         # Movements history
│   │   │   └── [id]/            # Movement details
│   │   │       └── page.tsx
│   │   ├── counts/              # Cycle counts
│   │   │   ├── page.tsx         # Count schedules
│   │   │   ├── new/             # Create count
│   │   │   └── [id]/            # Count execution
│   │   │       ├── page.tsx
│   │   │       └── components/
│   │   └── reports/             # Inventory reports
│   │       ├── page.tsx         # Reports dashboard
│   │       └── [type]/          # Specific report types
│   │           └── page.tsx
│   │
│   ├── products/                # Product management
│   │   ├── page.tsx             # Product catalog
│   │   ├── layout.tsx           # Products section layout
│   │   ├── new/                 # Create product
│   │   │   ├── page.tsx
│   │   │   └── components/
│   │   │       ├── product-form.tsx
│   │   │       ├── category-selector.tsx
│   │   │       └── image-uploader.tsx
│   │   ├── [id]/                # Product details
│   │   │   ├── page.tsx         # Product overview
│   │   │   ├── layout.tsx       # Product detail layout
│   │   │   ├── edit/            # Edit product
│   │   │   │   ├── page.tsx
│   │   │   │   └── components/
│   │   │   ├── inventory/       # Product inventory
│   │   │   │   └── page.tsx
│   │   │   ├── history/         # Product history
│   │   │   │   └── page.tsx
│   │   │   └── variants/        # Product variants
│   │   │       ├── page.tsx
│   │   │       └── new/
│   │   ├── categories/          # Category management
│   │   │   ├── page.tsx         # Categories list
│   │   │   ├── new/             # Create category
│   │   │   └── [id]/            # Category details
│   │   │       ├── page.tsx
│   │   │       └── edit/
│   │   ├── import/              # Bulk import
│   │   │   ├── page.tsx
│   │   │   └── components/
│   │   └── scan/                # Barcode scanning
│   │       ├── page.tsx
│   │       └── components/
│   │           └── barcode-scanner.tsx
│   │
│   ├── orders/                  # Order management
│   │   ├── page.tsx             # Orders overview
│   │   ├── layout.tsx           # Orders section layout
│   │   ├── purchase/            # Purchase orders
│   │   │   ├── page.tsx         # PO list
│   │   │   ├── new/             # Create PO
│   │   │   │   ├── page.tsx
│   │   │   │   └── components/
│   │   │   └── [id]/            # PO details
│   │   │       ├── page.tsx
│   │   │       ├── edit/
│   │   │       ├── receive/
│   │   │       └── components/
│   │   ├── sales/               # Sales orders
│   │   │   ├── page.tsx         # SO list
│   │   │   ├── new/             # Create SO
│   │   │   │   ├── page.tsx
│   │   │   │   └── components/
│   │   │   └── [id]/            # SO details
│   │   │       ├── page.tsx
│   │   │       ├── fulfill/
│   │   │       └── components/
│   │   └── transfers/           # Transfer orders
│   │       ├── page.tsx         # Transfers list
│   │       ├── new/             # Create transfer
│   │       └── [id]/            # Transfer details
│   │           └── page.tsx
│   │
│   ├── analytics/               # Reports and analytics
│   │   ├── page.tsx             # Analytics dashboard
│   │   ├── inventory/           # Inventory analytics
│   │   │   ├── page.tsx         # Inventory reports
│   │   │   └── [report]/        # Specific reports
│   │   │       └── page.tsx
│   │   ├── sales/               # Sales analytics
│   │   │   ├── page.tsx         # Sales reports
│   │   │   └── [report]/        # Specific reports
│   │   │       └── page.tsx
│   │   ├── purchasing/          # Purchasing analytics
│   │   │   └── page.tsx
│   │   └── performance/         # Performance metrics
│   │       └── page.tsx
│   │
│   ├── settings/                # Application settings
│   │   ├── page.tsx             # Settings overview
│   │   ├── layout.tsx           # Settings layout
│   │   ├── profile/             # User profile
│   │   │   └── page.tsx
│   │   ├── company/             # Company settings
│   │   │   └── page.tsx
│   │   ├── warehouses/          # Warehouse management
│   │   │   ├── page.tsx
│   │   │   ├── new/
│   │   │   └── [id]/
│   │   │       ├── page.tsx
│   │   │       └── edit/
│   │   ├── users/               # User management
│   │   │   ├── page.tsx
│   │   │   ├── new/
│   │   │   └── [id]/
│   │   │       ├── page.tsx
│   │   │       └── edit/
│   │   ├── integrations/        # Third-party integrations
│   │   │   └── page.tsx
│   │   └── system/              # System settings
│   │       └── page.tsx
│   │
│   └── help/                    # Help and documentation
│       ├── page.tsx             # Help center
│       ├── guides/              # User guides
│       │   ├── page.tsx
│       │   └── [guide]/
│       │       └── page.tsx
│       ├── api/                 # API documentation
│       │   └── page.tsx
│       └── support/             # Support contact
│           └── page.tsx

Public Routes

app/
├── (auth)/                      # Authentication route group
│   ├── layout.tsx               # Auth layout (centered, minimal)
│   ├── login/                   # Login page
│   │   ├── page.tsx
│   │   └── components/
│   │       ├── login-form.tsx
│   │       └── social-login.tsx
│   ├── register/                # Registration page
│   │   ├── page.tsx
│   │   └── components/
│   │       └── register-form.tsx
│   ├── forgot-password/         # Password reset
│   │   ├── page.tsx
│   │   └── components/
│   │       └── reset-form.tsx
│   └── verify/                  # Email verification
│       └── page.tsx
│
├── (marketing)/                 # Public marketing pages
│   ├── layout.tsx               # Marketing layout
│   ├── page.tsx                 # Landing page
│   ├── about/                   # About page
│   │   └── page.tsx
│   ├── features/                # Features page
│   │   └── page.tsx
│   ├── pricing/                 # Pricing page
│   │   └── page.tsx
│   ├── contact/                 # Contact page
│   │   ├── page.tsx
│   │   └── components/
│   │       └── contact-form.tsx
│   └── blog/                    # Blog section
│       ├── page.tsx
│       └── [slug]/
│           └── page.tsx
│
├── api/                         # API routes
│   ├── auth/                    # Authentication endpoints
│   │   ├── login/
│   │   │   └── route.ts
│   │   ├── logout/
│   │   │   └── route.ts
│   │   ├── register/
│   │   │   └── route.ts
│   │   └── verify/
│   │       └── route.ts
│   ├── products/                # Product endpoints
│   │   ├── route.ts             # List/create products
│   │   ├── [id]/                # Product CRUD
│   │   │   └── route.ts
│   │   ├── search/              # Product search
│   │   │   └── route.ts
│   │   └── categories/          # Product categories
│   │       ├── route.ts
│   │       └── [id]/
│   │           └── route.ts
│   ├── inventory/               # Inventory endpoints
│   │   ├── route.ts
│   │   ├── adjustments/
│   │   │   ├── route.ts
│   │   │   └── [id]/
│   │   │       └── route.ts
│   │   ├── movements/
│   │   │   ├── route.ts
│   │   │   └── [id]/
│   │   │       └── route.ts
│   │   └── reports/
│   │       └── route.ts
│   ├── orders/                  # Order endpoints
│   │   ├── purchase/
│   │   │   ├── route.ts
│   │   │   └── [id]/
│   │   │       └── route.ts
│   │   ├── sales/
│   │   │   ├── route.ts
│   │   │   └── [id]/
│   │   │       └── route.ts
│   │   └── transfers/
│   │       ├── route.ts
│   │       └── [id]/
│   │           └── route.ts
│   ├── analytics/               # Analytics endpoints
│   │   ├── inventory/
│   │   │   └── route.ts
│   │   ├── sales/
│   │   │   └── route.ts
│   │   └── performance/
│   │       └── route.ts
│   ├── users/                   # User management endpoints
│   │   ├── route.ts
│   │   └── [id]/
│   │       └── route.ts
│   ├── webhooks/                # Webhook endpoints
│   │   ├── stripe/
│   │   │   └── route.ts
│   │   └── inventory/
│   │       └── route.ts
│   └── upload/                  # File upload endpoints
│       ├── images/
│       │   └── route.ts
│       └── documents/
│           └── route.ts
│
├── globals.css                  # Global styles
├── layout.tsx                   # Root layout
├── loading.tsx                  # Global loading component
├── error.tsx                    # Global error boundary
├── not-found.tsx                # Global 404 page
└── page.tsx                     # Root page (redirects to app)

File Naming Conventions

Route Files

  • page.tsx: Page component for the route
  • layout.tsx: Layout component for nested routes
  • loading.tsx: Loading UI component
  • error.tsx: Error boundary component
  • not-found.tsx: 404 page component
  • route.ts: API route handler

Component Files

  • Pascal Case: ProductCard.tsx, UserProfile.tsx
  • Feature Prefix: ProductCreateForm.tsx, InventoryTable.tsx
  • Component Suffix: Clear indication of component type

Utility Files

  • Kebab Case: product-service.ts, auth-utils.ts
  • Descriptive Names: date-formatter.ts, api-client.ts
  • Type Files: product.types.ts, api.types.ts

Test Files

  • Co-location: ProductCard.test.tsx next to ProductCard.tsx
  • Test Suffix: .test.tsx, .test.ts
  • Spec Suffix: .spec.tsx, .spec.ts for integration tests

Organization Principles

1. Feature-Based Organization

features/
├── products/
│   ├── components/
│   ├── hooks/
│   ├── services/
│   ├── types/
│   └── utils/
├── inventory/
│   ├── components/
│   ├── hooks/
│   ├── services/
│   ├── types/
│   └── utils/
└── orders/
    ├── components/
    ├── hooks/
    ├── services/
    ├── types/
    └── utils/

2. Layer-Based Organization

components/
├── ui/                          # Basic UI components
├── forms/                       # Form components
├── layouts/                     # Layout components
└── features/                    # Feature-specific components

services/
├── api/                         # API services
├── auth/                        # Authentication services
└── data/                        # Data manipulation services

utils/
├── formatters/                  # Data formatting utilities
├── validators/                  # Validation utilities
└── helpers/                     # General helper functions

3. Domain-Driven Structure

domains/
├── product/
│   ├── entities/
│   ├── repositories/
│   ├── services/
│   └── use-cases/
├── inventory/
│   ├── entities/
│   ├── repositories/
│   ├── services/
│   └── use-cases/
└── order/
    ├── entities/
    ├── repositories/
    ├── services/
    └── use-cases/

Best Practices

1. Consistent Naming

  • Use descriptive, self-documenting names
  • Follow established conventions consistently
  • Use domain-specific terminology appropriately

2. Logical Grouping

  • Group related files together
  • Keep component and test files co-located
  • Separate concerns by feature or domain

3. Scalable Structure

  • Design for growth and maintainability
  • Avoid deep nesting where possible
  • Use barrel exports for clean imports

4. Clear Boundaries

  • Maintain clear separation between layers
  • Define explicit interfaces between modules
  • Avoid circular dependencies

This directory structure provides a solid foundation for organizing a scalable, maintainable Next.js application with clear separation of concerns and intuitive navigation.