📝 docs(project): add CLAUDE.md with development guidance

- document development commands including build and dev options
- describe architecture overview with frontend, backend, database and real-time components
- list key directories and their purposes
- explain database & ORM setup with TypeORM and entity locations
- document real-time features and authentication system
- add development notes about package manager, build tools and environment variables

CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Build Commands
+- `npm run build` - Build both client and server
+- `npm run build:client` - Build client only
+- `npm run build:server` - Build server only
+
+### Development Commands
+- `npm run dev` - Start development server (port 8080)
+- `npm run dev:stock` - Development with backend debug logging
+- `npm run dev:socket` - Development with socket debug logging
+- `npm run start` - Start production server
+
+## Architecture Overview
+
+This is a full-stack TypeScript application using:
+- **Frontend**: React 19 + Vite + Tailwind CSS
+- **Backend**: Hono.js framework with Express-style routing
+- **Database**: TypeORM with MySQL
+- **Real-time**: Socket.IO for WebSocket communication
+- **Authentication**: JWT-based auth with middleware
+
+### Key Directories
+- `src/client/` - Frontend React components and pages
+- `src/server/` - Backend API routes, middleware, and services
+- `src/server/api/` - Hono.js API route definitions
+- `src/server/modules/` - Business logic modules (users, auth, etc.)
+- `src/server/middleware/` - Authentication and custom middleware
+- `src/share/` - Shared types and utilities
+
+### Database & ORM
+- Uses TypeORM with MySQL2 driver
+- Entity files in `src/server/modules/*/*.entity.ts`
+- Database configuration in `src/server/data-source.ts`
+
+### Real-time Features
+- Socket.IO integration for real-time communication
+- Socket middleware for authentication
+- Socket handlers in `src/server/socket/`
+
+### Authentication System
+- JWT-based authentication
+- User roles: TEACHER, STUDENT, TRAINEE
+- Trainee expiration system with automatic status updates
+- Middleware in `src/server/middleware/`
+
+## Development Notes
+- Uses pnpm as package manager
+- Vite for both dev server and production builds
+- SSR (Server-Side Rendering) setup with Hono.js
+- Environment variables via `.env` file
+- Port 8080 for development and production