# 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

```text
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
```text
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
```text
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/*