MemeStudio/EXPLORATION_MANIFEST.md

# MemeStudio - Complete Exploration Manifest

## Files Analyzed

### 📄 Core Configuration Files
- ✅ `CLAUDE.md` - Project guidance (4KB)
- ✅ `.env.production` - Environment example (500B)
- ✅ `package.json` - Dependencies (1.6KB)
- ✅ `next.config.js` - Next.js config (330B)
- ✅ `middleware.ts` - Auth middleware (1KB)
- ✅ `tsconfig.json` - TypeScript config (230B)

### 🗄️ Database
- ✅ `prisma/schema.prisma` - 7 data models (2.5KB)

### 🔐 Authentication & Libraries
- ✅ `lib/auth.ts` - Better Auth config (430B)
- ✅ `lib/auth-client.ts` - Client auth hooks (300B)
- ✅ `lib/prisma.ts` - Prisma singleton (280B)
- ✅ `lib/api.ts` - apiFetch wrapper (200B)
- ✅ `lib/cos.ts` - Tencent COS utilities (2.5KB)
- ✅ `lib/utils.ts` - Tailwind utilities (140B)

### 📝 Type Definitions
- ✅ `types/index.ts` - All TypeScript interfaces (1.5KB)

### 🛣️ API Routes (11 files)
- ✅ `app/api/auth/[...all]/route.ts` - Better Auth handler (80B)
- ✅ `app/api/levels/route.ts` - Levels CRUD (4.5KB)
- ✅ `app/api/levels/reorder/route.ts` - Batch reorder (1.2KB)
- ✅ `app/api/users/route.ts` - User management (5.5KB)
- ✅ `app/api/cos/temp-key/route.ts` - COS credentials (900B)
- ✅ `app/api/wx-users/route.ts` - WeChat users list (2KB)
- ✅ `app/api/wx-users/[id]/route.ts` - User details (1.8KB)
- ✅ `app/api/wx-users/level-progress/route.ts` - Progress delete (1KB)

### 📄 Pages (3 main pages)
- ✅ `app/(dashboard)/levels/page.tsx` - Levels management UI (5KB)
- ✅ `app/(dashboard)/users/page.tsx` - User management UI (7.5KB)
- ✅ `app/(dashboard)/wx-users/page.tsx` - WeChat users UI (6KB)
- ✅ `app/layout.tsx` - Root layout (500B)
- ✅ `app/page.tsx` - Home redirect (120B)

### 🎨 Components (15+ files)
- ✅ `components/layout/header.tsx` - Header component (600B)
- ✅ `components/levels/level-dialog.tsx` - Create/edit dialog (4.5KB)
- ✅ `components/layout/sidebar.tsx` - Navigation
- ✅ `components/levels/level-list.tsx` - Drag-and-drop list
- ✅ `components/levels/level-card.tsx` - Level card
- ✅ `components/levels/image-uploader.tsx` - Image upload
- ✅ `components/users/user-dialog.tsx` - User form
- ✅ `components/wx-users/wx-user-detail-dialog.tsx` - User details
- ✅ `components/ui/*` - shadcn/ui components (buttons, inputs, dialogs, etc.)

---

## Analysis Summary

### Total Files Reviewed: 30+

### Key Statistics
- **Total API Routes**: 14 endpoints across 8 route files
- **Database Models**: 7 (User, Session, Account, Verification, Level, WxUser, WxUserLevelProgress)
- **Protected Pages**: 3 (levels, users, wx-users)
- **Public Pages**: 1 (login)
- **UI Components**: 15+
- **Utility Libraries**: 6 key files
- **Dependencies**: 30+ npm packages

### Code Structure Quality
- ✅ Well-organized folder structure
- ✅ Consistent naming conventions
- ✅ Type safety throughout (TypeScript)
- ✅ Error handling in all endpoints
- ✅ Session validation patterns consistent
- ✅ React Query for state management
- ✅ Component composition is clean

---

## Key Findings

### 1. Architecture
- **Framework**: Next.js 14 with App Router
- **Deployment Model**: Standalone (single binary)
- **Reverse Proxy**: Behind `/studio` basePath
- **Auth System**: Better Auth with MySQL Prisma adapter
- **Session Duration**: 7 days with 1-day update age

### 2. Database Design
- **Provider**: MySQL
- **ORM**: Prisma v6.5.0
- **Models**: 7 total (Better Auth + custom models)
- **Relationships**: One-to-many (WxUser → WxUserLevelProgress → Level)
- **Cascade Delete**: Implemented for Sessions/Accounts

### 3. API Patterns
- **Auth Check**: All routes validate session before proceeding
- **Error Handling**: Consistent error responses
- **Validation**: Input validation in all POST/PUT routes
- **Transactions**: Used for multi-step operations (user creation, reordering)
- **Pagination**: Implemented for WeChat users list

### 4. Security
- ✅ Session-based authentication
- ✅ Password hashing (bcryptjs + better-auth/crypto)
- ✅ Cookie validation (handles HTTP and HTTPS prefixes)
- ✅ Self-delete prevention in user management
- ✅ Temporary COS credentials (30-minute expiry)

### 5. Notable Gotchas
- ⚠️ BETTER_AUTH_URL must NOT contain path component
- ⚠️ basePath excluded from request.nextUrl.pathname in Next.js 14
- ⚠️ Middleware uses cookie check only (no Prisma in Edge Runtime)
- ⚠️ HTTPS adds `__Secure-` prefix to cookies
- ⚠️ apiFetch() must be used for client-side API calls

### 6. Missing Features
- ❌ No sharing/invite system
- ❌ No permission/role system
- ❌ No audit logging
- ❌ No soft deletes
- ❌ No rate limiting
- ❌ All authenticated users have full admin access

---

## Frontend Technology Stack

- **React**: 18.3.1
- **TypeScript**: 5.8.2
- **Tailwind CSS**: 3.4.17
- **shadcn/ui**: Latest (Radix UI based)
- **React Query**: TanStack v5.69.0
- **React Hook Form**: 7.54.2
- **Zod**: 3.24.2 (validation)
- **@dnd-kit**: For drag-and-drop (sortable)
- **lucide-react**: Icons (0.483.0)

---

## Backend Technology Stack

- **Next.js**: 14.2.28 (App Router)
- **Better Auth**: 1.2.7
- **Prisma**: 6.5.0
- **MySQL**: Database
- **Node.js**: Runtime
- **Tencent COS**: Cloud storage
- **bcryptjs**: Password hashing

---

## Development Commands

```bash
# Development
pnpm run dev              # Start dev server (port 3001)

# Build & Deploy
pnpm run build            # Production build
pnpm run deploy           # Build + deploy via SSH

# Linting
pnpm run lint             # ESLint

# Database
pnpm run db:generate      # Generate Prisma client
pnpm run db:push          # Push schema (dev)
pnpm run db:migrate       # Create migration
pnpm run db:studio        # Open Prisma Studio (visual editor)
pnpm run db:seed          # Create/update admin user
```

---

## Deployment Information

**Server Details**:
- **Host**: `root@119.91.211.52`
- **Path**: `/root/apps/meme-studio`
- **Process Manager**: PM2
- **Staging Path**: `/studio` (behind reverse proxy)

**Deployment Process**:
1. Local build: `pnpm run build`
2. Remote setup: `npm install --production`
3. Database: `npx prisma generate`
4. Process: PM2 restart

**Critical Configuration**:
- `output: 'standalone'` - Bundles Next.js runtime
- `basePath: '/studio'` - App served at /studio
- Image remotes: `*.myqcloud.com` (Tencent COS)

---

## Search Findings

**No share/invite logic found** ❌
- Searched entire codebase for "share", "invite", "permission"
- No models, APIs, or UI components for sharing
- No role-based access control
- All authenticated users = full admin access

---

## Project Health Indicators

✅ **Strengths**:
- Clean code organization
- Consistent patterns
- Good error handling
- Type-safe throughout
- RESTful API design
- Proper session management
- Transaction support in DB

⚠️ **Considerations**:
- No permission system
- No audit logging
- No sharing/invite feature
- Single deployment server
- No multi-environment setup documented
- Email verification model exists but not used

---

## Next Steps for Development

If expanding this project:

1. **Add Permissions System**
   - Add role field to User model
   - Implement permission checks in API routes
   - Add UI for role assignment

2. **Implement Sharing**
   - Create ShareToken model
   - Add share generation endpoints
   - Add permission validation on share access

3. **Add Audit Logging**
   - Create AuditLog model
   - Log all CRUD operations
   - Track user actions

4. **Multi-Environment**
   - Separate env configs (dev, staging, prod)
   - Add database migrations
   - Document deployment process

5. **API Security**
   - Add rate limiting
   - Implement CORS policies
   - Add request validation schemas

---

## Documentation Generated

Two comprehensive documents created:

1. **PROJECT_ANALYSIS.md** (14 sections, 1000+ lines)
   - Complete architecture breakdown
   - All API endpoint documentation
   - Database schema details
   - Auth flow explanation
   - Deployment information
   - Common patterns and gotchas

2. **QUICK_REFERENCE.md** (Visual guide)
   - Architecture diagram
   - Quick lookup tables
   - Common tasks
   - Critical gotchas
   - Quick stats

Both files saved to: `/Users/richard/Documents/code/xieyingeng/MemeStudio/`