Directory Structure

How frontend code is organized in this project, optimized for Next.js and React.

Overview

This project follows a modular and concern-separated structure. We prioritize colocation (keeping related code close to where it's used) while maintaining a clean global src/ directory for shared resources.

Next.js App Router: Used for routing and layouts.
Component-Driven: UI is split into atomic common components and module-specific business components.
Strict Naming: Enforces consistency across the codebase.

Directory Layout

src/
├── app/                # Next.js App Router (Routes, Layouts, Pages)
│   ├── (auth)/         # Route group (e.g., login, register)
│   ├── dashboard/      # Dashboard module
│   │   ├── components/ # Local components (kebab-case)
│   │   ├── hooks/      # Local hooks (camelCase)
│   │   ├── services/   # Local API calls/logic
│   │   ├── page.tsx    # Page entry
│   │   └── layout.tsx  # Nested layout
│   ├── globals.css     # Global styles entry
│   └── layout.tsx      # Root layout
├── api/                # Global Axios instances and shared API clients
├── assets/             # Static assets (images, fonts, SVGs)
├── components/         # Global reusable UI components
│   ├── common/         # Atomic UI components (e.g., /my-button)
│   └── business/       # Shared business components (e.g., /user-select)
├── hooks/              # Global custom hooks (e.g., useAuth.ts)
├── layouts/            # Shared layout wrappers (non-routing layouts)
├── store/              # State management (Zustand stores)
├── styles/             # Global style configurations (Tailwind, Mixins)
├── types/              # Global TypeScript interfaces and entities
└── utils/              # Global utility/helper functions

Module Organization

Global vs. Local

Global: If a component, hook, or util is used by 3 or more routes, move it to the root src/components/, src/hooks/, or src/utils/.
Local: If it's specific to a single feature, keep it inside that feature's directory in src/app/....

The app/ Directory (Routing)

We use Route Groups (folders with parentheses, e.g., (auth)) to organize routes without affecting the URL.
Each route folder should ideally contain its own page.tsx, and if complex, its own components/ sub-folder.

Naming Conventions

Folders

Component Folders: Use kebab-case (e.g., src/components/common/search-bar/).
Other Folders: Use camelCase (e.g., src/hooks/, src/utils/, src/api/).
Next.js Routing: Follows Next.js standards (kebab-case for URL segments).

Files

React Components: reveal.tsx inside the component folder.
Hooks: use prefix with camelCase (e.g., useDebounce.ts).
Styles: *.module.scss or *.css (if using Scoped CSS).
Types: *.types.ts or types.ts.

Examples

A Standard Business Component

src/components/business/user-profile-card/
├── reveal.tsx          # Component logic
├── user-avatar.tsx    # Sub-component
├── types.ts           # Local types
└── style.module.scss  # Local styles

A Route Module

src/app/dashboard/settings/
├── components/        # Components only used in Settings
│   └── profile-form/
├── hooks/             # Hooks only used in Settings
│   └── useSettings.ts
├── page.tsx           # Entry point for /dashboard/settings
└── layout.tsx         # Layout for settings pages

Path Aliases

To avoid deep nesting like ../../../../components, use the following aliases:

@/* -> src/*
@api/* -> src/api/*
@comp/* -> src/components/*
@hooks/* -> src/hooks/*

3.8 KiB Raw Blame History