首页

.trellis/spec/frontend/directory-structure.md

@@ -0,0 +1,88 @@
+# 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/*