# 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*