# Codebase Structure

**Analysis Date:** 2026-05-07

## Directory Layout

```
qy-lty-admin/
├── app/                          # Next.js App Router pages & layouts
│   ├── layout.tsx                # Root layout with metadata
│   ├── page.tsx                  # Dashboard homepage
│   ├── login/page.tsx            # Login page
│   ├── register/page.tsx         # Registration page
│   ├── forgot-password/page.tsx  # Password reset page
│   ├── ai-model/page.tsx         # AI Model management
│   ├── outfits/                  # Outfit content module
│   │   ├── page.tsx              # List view
│   │   ├── [id]/page.tsx         # Detail view
│   │   ├── edit/[id]/page.tsx    # Edit form
│   │   └── loading.tsx           # Loading skeleton
│   ├── props/                    # Props module (same structure as outfits)
│   ├── home-decor/               # Home decor module
│   ├── food/                     # Food module
│   ├── songs/                    # Songs module
│   ├── dances/                   # Dances module
│   ├── achievements/             # Achievements module
│   ├── affinity/                 # Affinity/favorability module
│   ├── users/                    # User management module
│   ├── permissions/              # Permissions management module
│   ├── settings/                 # System settings module
│   └── globals.css               # Global Tailwind + custom styles
├── components/                   # Reusable React components
│   ├── ui/                       # Shadcn-style primitive components (copy-paste)
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── dialog.tsx
│   │   ├── input.tsx
│   │   ├── label.tsx
│   │   ├── table.tsx
│   │   ├── tabs.tsx
│   │   ├── select.tsx
│   │   ├── form.tsx
│   │   ├── alert-dialog.tsx
│   │   └── ... (30+ primitive components)
│   ├── outfits/                  # Outfit feature components
│   │   ├── OutfitsList.tsx
│   │   ├── OutfitsTable.tsx
│   │   ├── AddOutfitDialog.tsx
│   │   └── OutfitDetailCard.tsx
│   ├── songs/                    # Songs feature components
│   ├── dances/                   # Dances feature components
│   ├── food/                     # Food feature components
│   ├── home-decor/               # Home decor feature components
│   ├── props/                    # Props feature components
│   ├── affinity/                 # Affinity feature components
│   ├── achievements/             # Achievements feature components
│   ├── permissions/              # Permissions feature components
│   ├── users/                    # Users feature components
│   ├── sidebar.tsx               # Main navigation sidebar (client)
│   ├── dashboard-shell.tsx       # Layout wrapper with permission checks (client)
│   ├── dashboard-header.tsx      # Page header component
│   ├── overview.tsx              # Dashboard overview chart
│   ├── recent-activity.tsx       # Recent activity feed
│   ├── stat-card.tsx             # KPI stat card
│   ├── delete-confirmation-dialog.tsx
│   ├── publish-confirmation-dialog.tsx
│   ├── theme-provider.tsx
│   └── add-outfit-dialog.tsx     # Shared modal for outfit creation
├── lib/                          # Utilities, types, API clients
│   ├── api/
│   │   ├── client.ts             # Axios instance + interceptors + interfaces
│   │   ├── auth.ts               # Login, logout, token management
│   │   ├── outfits.ts            # Outfit CRUD operations
│   │   ├── props.ts              # Props CRUD operations
│   │   ├── songs.ts              # Songs CRUD operations
│   │   ├── dances.ts             # Dances CRUD operations
│   │   ├── food.ts               # Food CRUD operations
│   │   ├── home-decor.ts         # Home decor CRUD operations
│   │   ├── achievements.ts       # Achievements CRUD operations
│   │   ├── affinity.ts           # Affinity system API
│   │   ├── ai-models.ts          # AI model management
│   │   ├── users.ts              # User management
│   │   ├── roles.ts              # Role/permission management
│   │   ├── error-handler.ts      # Centralized error handling
│   │   ├── adapters.ts           # Response schema mappers
│   │   ├── types.ts              # Shared API type definitions
│   │   ├── token-debug.ts        # Token debugging utilities
│   │   ├── card.ts               # Card-related API
│   │   └── index.ts              # Export barrel
│   ├── permissions.ts            # RBAC matrix + permission utilities
│   └── utils.ts                  # Utility functions (Tailwind cn)
├── hooks/                        # Custom React hooks
│   ├── use-mobile.tsx            # Mobile breakpoint detection hook
│   └── use-toast.ts              # Toast notification hook
├── middleware.ts                 # Next.js route protection middleware
├── public/                       # Static assets
├── styles/                       # Additional stylesheets (if any)
├── package.json                  # Dependencies & scripts
├── tsconfig.json                 # TypeScript configuration
├── tailwind.config.ts            # Tailwind CSS configuration
├── postcss.config.mjs            # PostCSS configuration
├── next.config.mjs               # Next.js configuration
├── Dockerfile                    # Docker build (yarn + Taobao mirror)
├── docker-compose.yml            # Local dev Docker Compose
├── README.md                     # Project overview & permissions matrix
├── CLAUDE.md                     # Codebase instructions for Claude
└── docs/
    └── 修改记录.md              # Change log (Chinese)
```

## Directory Purposes

**app/:**
- Purpose: Next.js App Router pages and layouts; each module has a folder with page.tsx + optional nested routes
- Contains: Page components ("use client"), form pages, dynamic routes with [id]
- Key files: `page.tsx` (list), `[id]/page.tsx` (detail), `edit/[id]/page.tsx` (edit form), `loading.tsx` (skeleton)

**components/:**
- Purpose: Reusable React components organized by feature
- Contains: UI primitives (components/ui/), feature-specific components (components/[feature]/), layout components (sidebar, shell)
- Key pattern: Feature folders mirror app module structure; components within are sub-components (no subfolders unless complex)

**components/ui/:**
- Purpose: Shadcn-style copy-paste UI primitives
- Contains: 30+ Base UI components (Button, Card, Dialog, Form, Table, Tabs, Select, etc.)
- Note: These are copied into the repo, not npm packages; safe to modify directly

**lib/api/:**
- Purpose: HTTP client and API communication layer
- Contains: Axios singleton instance, interceptors, module-specific API functions, response adapters, type definitions
- Pattern: One file per backend module (outfits.ts, songs.ts, etc.) + shared client.ts

**lib/:**
- Purpose: Shared utilities, types, configuration
- Contains: permissions.ts (RBAC logic), utils.ts (Tailwind helpers), api/ subfolder

**hooks/:**
- Purpose: Custom React hooks
- Contains: use-mobile (responsive detection), use-toast (notification system)

**middleware.ts:**
- Purpose: Next.js request middleware for route protection
- Functionality: Checks Cookie auth_token; redirects to /login if missing; whitelists public routes

**public/:**
- Purpose: Static assets (images, icons, etc.)

**styles/:**
- Purpose: Additional CSS if needed (most styling via Tailwind in components)

## Key File Locations

**Entry Points:**
- `app/layout.tsx`: Root layout (metadata only)
- `app/page.tsx`: Dashboard homepage (stats, charts, links)
- `app/login/page.tsx`: Authentication entry point
- `middleware.ts`: Route protection middleware

**Configuration:**
- `next.config.mjs`: Next.js config (standalone output)
- `tsconfig.json`: TypeScript strict mode
- `tailwind.config.ts`: Tailwind CSS theme + animations
- `postcss.config.mjs`: PostCSS with Tailwind + autoprefixer
- `.env.local`: Environment variables (API_BASE_URL)

**Core Logic:**
- `lib/permissions.ts`: Role-based access control matrix & utilities
- `lib/api/client.ts`: Axios instance with auth/error interceptors
- `components/dashboard-shell.tsx`: Permission-checking layout wrapper
- `components/sidebar.tsx`: Role-filtered navigation menu

**Authentication:**
- `lib/api/auth.ts`: Login, logout, token persistence
- `middleware.ts`: Route-level token validation

**Testing:**
- No test files detected; testing not yet set up

## Naming Conventions

**Files:**
- **Page components:** `page.tsx` (App Router standard)
- **Feature pages:** `/app/[module]/page.tsx` (e.g., app/outfits/page.tsx)
- **Dynamic routes:** `/app/[module]/[id]/page.tsx` (e.g., app/outfits/[id]/page.tsx)
- **Layout files:** `layout.tsx`
- **Loading states:** `loading.tsx`
- **API modules:** `/lib/api/[feature].ts` (e.g., lib/api/outfits.ts)
- **Component files:** PascalCase (e.g., OutfitsList.tsx, AddOutfitDialog.tsx)
- **Hook files:** `use-[name].ts` (e.g., use-mobile.tsx)

**Directories:**
- **App modules:** kebab-case (e.g., `/app/ai-model`, `/app/home-decor`, `/app/forgot-password`)
- **Component folders:** kebab-case for feature groups, `ui` for primitives
- **API folder:** All in `lib/api/` (no nested folders)

**Functions:**
- **API functions:** camelCase, verb-first (e.g., `getOutfits()`, `createOutfit()`, `updateOutfit()`)
- **Utility functions:** camelCase (e.g., `hasPermission()`, `getUserRole()`)
- **Components:** PascalCase (e.g., `DashboardShell`, `Sidebar`, `OutfitsList`)
- **Hooks:** camelCase with `use` prefix (e.g., `useMobile`, `useToast`)

**Variables/Constants:**
- **Type definitions:** PascalCase (e.g., `Outfit`, `RoleName`, `ApiResponse`)
- **Constants:** UPPER_SNAKE_CASE (e.g., `API_BASE_URL`, `PERMISSION_MATRIX`)
- **Local variables:** camelCase (e.g., `outfits`, `isLoading`, `userRole`)

**Routes:**
- **Module routes:** kebab-case URLs (e.g., `/ai-model`, `/home-decor`, `/forgot-password`)
- **Dynamic routes:** `[paramName]` (e.g., `/outfits/[id]`, `/dances/[id]/edit`)

## Where to Add New Code

**New Feature Module (e.g., New Content Type):**

1. **Page component:** Create `app/[module-name]/page.tsx`
   - Wrap with DashboardShell
   - Import feature components from `components/[module-name]/`
   - Call API functions from `lib/api/[module-name].ts`
   
2. **API client:** Create `lib/api/[module-name].ts`
   - Export `get[Feature]s()`, `get[Feature]()`, `create[Feature]()`, `update[Feature]()`, `delete[Feature]()`
   - Use `apiClient.get/post/put/delete()` from `lib/api/client.ts`
   - Include adapter function to map backend response to frontend type
   - Export types or import from `lib/api/types.ts`

3. **Components:** Create `components/[module-name]/` folder
   - List component (e.g., `[Feature]List.tsx`)
   - Detail/edit component
   - Dialog/modal for creation
   - Table component if displaying tabular data

4. **Permission matrix:** Add to `lib/permissions.ts`
   - Add module key to `PermissionModule` type
   - Add module to relevant roles in `PERMISSION_MATRIX`
   - Add path mapping in `getModuleFromPath()`

5. **Sidebar:** Update `components/sidebar.tsx`
   - Add menu item to appropriate section (AI Admin, Content Admin, or System Admin)
   - Use lucide-react icon

6. **Middleware:** Update `middleware.ts`
   - Add route to `protectedPaths` array if requiring auth

**New Component:**
- Location: `components/[feature-name]/[ComponentName].tsx`
- Import from UI primitives: `components/ui/button.tsx`, etc.
- Use React Hook Form for forms
- Use icons from lucide-react
- Mark as "use client" if using hooks/state

**New Utility Function:**
- Location: `lib/utils.ts` (for generic utilities) or `lib/api/[module].ts` (for API helpers)
- Type everything with TypeScript
- Export from `lib/api/index.ts` if API-related

**New Hook:**
- Location: `hooks/use-[name].ts`
- Follow React hook naming convention (use- prefix)

## Special Directories

**components/ui/:**
- Purpose: Shadcn-style primitives (Button, Card, Dialog, Form, Input, etc.)
- Generated: No (manually copied from shadcn/ui)
- Committed: Yes (safe to modify without breaking npm upgrades)
- Note: Each file is a single component; complex components like Dialog may have sub-exports

**public/:**
- Purpose: Static assets served at root level
- Generated: No
- Committed: Yes

**node_modules/:**
- Purpose: Installed dependencies
- Generated: Yes (by npm/pnpm/yarn)
- Committed: No (.gitignore)

**.next/:**
- Purpose: Next.js build output
- Generated: Yes (by `npm run build`)
- Committed: No (.gitignore)

**lib/api/:**
- Purpose: All API communication in one folder for easy discovery
- Generated: No (hand-written)
- Committed: Yes
- Note: No subfolders; keep flat for single-module-per-file pattern

---

*Structure analysis: 2026-05-07*
