math2-platform/backend/README.md

# Math Platform Backend

Backend API for the Linear Algebra Learning Platform built with Node.js, Express, TypeScript, Prisma, and PostgreSQL.

## Features

- **RESTful API** with Express.js
- **Type-safe** with TypeScript
- **ORM** with Prisma
- **Database** with PostgreSQL
- **Caching** with Redis
- **Authentication** with JWT
- **Rate Limiting** with Redis-backed storage
- **Structured Logging** with Winston
- **PDF Processing** with pdf-parse and pdf2pic
- **AI Integration** with MiniMax-M2.5 (Aliyun DashScope)
- **Telegram Notifications** (backend-only)
- **Queue System** with Bull
- **Docker Support** for containerization

## Tech Stack

- **Runtime**: Node.js 20 LTS
- **Framework**: Express.js 4.x
- **Language**: TypeScript 5.x
- **Database**: PostgreSQL 15
- **ORM**: Prisma 5.x
- **Cache/Queue**: Redis 7
- **Authentication**: JWT + bcrypt
- **Validation**: Zod
- **Logging**: Winston
- **Math Rendering**: KaTeX
- **AI**: MiniMax-M2.5 (OpenAI-compatible)

## Project Structure

```
backend/
├── prisma/
│   └── schema.prisma           # Prisma schema with all entities
├── src/
│   ├── config/
│   │   ├── auth/               # Authentication configuration
│   │   ├── database/           # Database configuration
│   │   ├── redis/              # Redis configuration
│   │   └── ai/                 # AI service configuration
│   ├── modules/
│   │   ├── auth/               # Authentication module
│   │   ├── pdf/                # PDF processing module
│   │   ├── exercise/           # Exercise management module
│   │   ├── module/             # Module management module
│   │   ├── progress/           # Progress tracking module
│   │   ├── ranking/            # Ranking system module
│   │   ├── notification/       # Notification module
│   │   └── user/               # User management module
│   ├── shared/
│   │   ├── database/           # Prisma client setup
│   │   ├── middleware/         # Express middleware
│   │   ├── utils/              # Utility functions
│   │   └── types/              # TypeScript types
│   ├── workers/                # Background workers
│   └── server.ts               # Main server file
├── .env.example                # Environment variables template
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md
```

## Database Schema

### Core Entities

1. **User** - User accounts with authentication
2. **Module** - 3 pedagogical modules (Fundamentals, Systems/Spaces, Applications)
3. **Topic** - 5 topics (Vectors, Matrices, Systems, Vector Spaces, Linear Programming)
4. **Exercise** - Exercises with LaTeX formulas
5. **ExerciseAttempt** - User exercise attempts
6. **Progress** - User progress per module
7. **Achievement** - Gamification badges/achievements
8. **UserAchievement** - Unlocked achievements
9. **Ranking** - Leaderboard positions (global and per module)
10. **Notification** - Telegram notifications (backend only)
11. **ProcessedPdf** - Processed PDF metadata

### Enums

- **ModuleType**: FUNDAMENTOS, SISTEMAS_ESPACIOS, APLICACIONES
- **TopicType**: VECTORES, MATRICES, SISTEMAS, ESPACIOS_VECTORIALES, PROGRAMACION_LINEAL
- **ExerciseType**: MULTIPLE_CHOICE, OPEN_RESPONSE, CALCULATION, PROOF, TRUE_FALSE
- **ExerciseDifficulty**: BASIC, INTERMEDIATE, ADVANCED, EXPERT
- **AttemptStatus**: CORRECT, INCORRECT, PARTIAL, PENDING
- **AchievementCategory**: EXERCISES, MODULES, STREAKS, RANKING, SPECIAL
- **AchievementRarity**: COMMON, RARE, EPIC, LEGENDARY

## Getting Started

### Prerequisites

- Node.js 20+ LTS
- PostgreSQL 15
- Redis 7
- Docker (optional, for containerization)

### Installation

1. **Clone the repository**
   ```bash
   cd /home/ren/Documents/math2/backend
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Set up environment variables**
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

4. **Set up the database**
   ```bash
   # Generate Prisma client
   npm run prisma:generate

   # Run migrations
   npm run prisma:migrate

   # (Optional) Seed database
   npm run prisma:seed
   ```

5. **Start the development server**
   ```bash
   npm run dev
   ```

The API will be available at `http://localhost:3001`

## API Endpoints

### Authentication
- `POST /api/auth/register` - Register new user
- `POST /api/auth/login` - Login user
- `GET /api/auth/me` - Get current user profile
- `POST /api/auth/refresh` - Refresh access token
- `POST /api/auth/logout` - Logout user

### Modules
- `GET /api/modules` - List all modules
- `GET /api/modules/:id` - Get module details
- `GET /api/modules/:id/introduction` - Get module introduction
- `GET /api/modules/:id/examples` - Get module examples
- `GET /api/modules/:id/exercises` - Get module exercises
- `GET /api/modules/:id/answers` - Get module answers

### Topics
- `GET /api/topics` - List all topics
- `GET /api/topics/:id` - Get topic details
- `GET /api/topics/:id/theory` - Get topic theory content

### Exercises
- `GET /api/exercises` - List exercises
- `GET /api/exercises/:id` - Get exercise details
- `POST /api/exercises/:id/attempt` - Submit exercise attempt
- `GET /api/exercises/:id/solution` - Get exercise solution

### Progress
- `GET /api/progress` - Get overall progress
- `GET /api/progress/module/:moduleId` - Get progress for specific module

### Ranking
- `GET /api/ranking/global` - Get global ranking
- `GET /api/ranking/module/:moduleId` - Get ranking for specific module
- `GET /api/ranking/my-position` - Get current user's position

### Achievements
- `GET /api/achievements` - List all available achievements
- `GET /api/achievements/my` - Get user's achievements

### AI Generation
- `POST /api/ai/generate-exercise` - Generate new exercise with AI
- `POST /api/ai/validate-answer` - Validate answer with AI

## Environment Variables

See `.env.example` for all available environment variables. Key variables include:

- `DATABASE_URL` - PostgreSQL connection string
- `REDIS_HOST` - Redis server host
- `JWT_SECRET` - Secret for JWT signing
- `AI_API_KEY` - API key for AI service
- `TELEGRAM_BOT_TOKEN` - Telegram bot token (backend notifications)

## Development Scripts

```bash
npm run dev              # Start development server with hot reload
npm run build            # Build for production
npm start                # Start production server
npm run prisma:generate  # Generate Prisma client
npm run prisma:migrate   # Run database migrations
npm run prisma:studio    # Open Prisma Studio
npm test                 # Run tests
npm run lint             # Lint code
npm run format           # Format code with Prettier
```

## Docker Usage

```bash
# Build image
docker build -t math-backend .

# Run container
docker run -p 3001:3001 --env-file .env math-backend

# Use Docker Compose (from root directory)
docker-compose up backend
```

## API Documentation

API documentation is available using OpenAPI/Swagger. Access it at:
- Production: `http://localhost:3001/api-docs`

## Testing

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

## Error Handling

The API uses standard HTTP status codes and returns error responses in the following format:

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z",
    "requestId": "req_xxx"
  }
}
```

## Logging

Logs are stored in the `logs/` directory:
- `combined.log` - All logs
- `error.log` - Error logs only

Logs are structured JSON with correlation IDs for request tracing.

## Security Features

- JWT-based authentication
- Password hashing with bcrypt
- Rate limiting (Redis-backed)
- CORS configuration
- Helmet.js security headers
- Input validation with Zod
- SQL injection prevention (Prisma)
- XSS protection

## Performance Optimization

- Database connection pooling
- Redis caching
- Indexed database queries
- Compression middleware
- Optimized Prisma queries
- Background workers for heavy tasks

## Contributing

1. Follow the existing code style
2. Write tests for new features
3. Update documentation
4. Use TypeScript for type safety
5. Follow git commit conventions

## License

MIT

## Support

For issues or questions, please create an issue in the repository.