math2-platform/backend/QUICK_START.md

Backend Quick Start Guide

Initial Setup

1. Install Dependencies

cd /home/ren/Documents/math2/backend
npm install

2. Configure Environment Variables

cp .env.example .env
nano .env  # Edit with your configuration

Required variables to update:

• DATABASE_URL - PostgreSQL connection string
• JWT_SECRET - Generate a secure random string
• AI_API_KEY - Your AI service API key
• TELEGRAM_BOT_TOKEN - Your Telegram bot token (if using)

3. Generate Prisma Client

npm run prisma:generate

4. Create and Run Migrations

# Create initial migration
npm run prisma:migrate

# Or reset database (WARNING: deletes all data)
npm run prisma:reset

5. Seed Database

npm run prisma:seed

This will create:

• 3 Modules (Fundamentos, Sistemas/Espacios, Aplicaciones)
• 5 Topics (Vectores, Matrices, Sistemas, Espacios Vectoriales, Programación Lineal)
• 18 Achievements/Badges
• System configuration

6. Start Development Server

npm run dev

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

Development Workflow

Running the Server

# Development with hot reload
npm run dev

# Production build
npm run build
npm start

Database Operations

# Open Prisma Studio (GUI)
npm run prisma:studio

# Generate client after schema changes
npm run prisma:generate

# Create migration
npm run prisma:migrate

# Reset database
npm run prisma:reset

# Seed database
npm run prisma:seed

Code Quality

# Type checking
npm run type-check

# Linting
npm run lint
npm run lint:fix

# Format code
npm run format

# Run tests
npm test
npm run test:watch
npm run test:coverage

API Endpoints (Placeholder)

Once routes are implemented:

Health Check

• GET /health - Server health status
• GET /api/health - API health status

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login
• GET /api/auth/me - Get current user

Modules

• GET /api/modules - List all modules
• GET /api/modules/:id - Get module details

More endpoints to be implemented...

Database Schema Overview

Core Entities

• User - User accounts
• Module - 3 pedagogical modules
• Topic - 5 mathematical topics
• Exercise - Exercises with LaTeX
• ExerciseAttempt - User attempts
• Progress - Module progress
• Achievement - 18 gamification badges
• UserAchievement - Unlocked badges
• Ranking - Leaderboards
• Notification - Telegram notifications
• ProcessedPdf - PDF processing metadata

Key Features

• Type-safe with Prisma + TypeScript
• Indexed queries for performance
• Cascade deletes for integrity
• JSON fields for flexible content
• Enum types for data validation

Architecture

backend/
├── prisma/
│   ├── schema.prisma        # Database schema
│   └── seed.ts              # Database seeding
├── src/
│   ├── config/              # Configuration modules
│   ├── modules/             # Feature modules (auth, exercise, etc.)
│   ├── shared/              # Shared utilities
│   │   ├── database/        # Prisma client
│   │   ├── middleware/      # Express middleware
│   │   ├── types/           # TypeScript types
│   │   ├── utils/           # Utilities (logger, etc.)
│   │   └── constants/       # Application constants
│   ├── workers/             # Background workers
│   └── server.ts            # Main server
└── [config files]

Troubleshooting

Database Connection Issues

1. Check PostgreSQL is running:

sudo systemctl status postgresql

2. Test connection:

psql -h localhost -U mathuser -d mathdb

3. Check DATABASE_URL in .env

Prisma Issues

1. Regenerate client:

npm run prisma:generate

2. Reset migrations:

npm run prisma:reset

3. Check schema:

npm run prisma:studio

Port Already in Use

# Find process using port 3001
lsof -i :3001

# Kill process
kill -9 <PID>

# Or change port in .env
PORT=3002

Redis Connection Issues

1. Check Redis is running:

redis-cli ping

2. Start Redis:

sudo systemctl start redis

3. Check connection settings in .env

Next Steps

1. Implement Routes

   • Create controllers in /src/modules/*/
   • Implement business logic
   • Add validation schemas

2. Create Workers

   • PDF processing worker
   • Exercise generation worker
   • Notification worker

3. Add Tests

   • Unit tests
   • Integration tests
   • E2E tests

4. Setup Docker

   • Create Dockerfile
   • Configure docker-compose
   • Test container deployment

Useful Commands

# Check database health
curl http://localhost:3001/health

# View logs
tail -f logs/combined.log
tail -f logs/error.log

# Database backup
docker exec postgres pg_dump -U mathuser mathdb > backup.sql

# Restore database
docker exec -T postgres psql -U mathuser mathdb < backup.sql

Environment Variables Reference

See .env.example for all available variables. Key variables:

• PORT - Server port (default: 3001)
• DATABASE_URL - PostgreSQL connection string
• REDIS_HOST - Redis server host
• JWT_SECRET - JWT signing secret
• AI_API_KEY - AI service API key
• TELEGRAM_BOT_TOKEN - Telegram bot token
• NODE_ENV - Environment (development/production)

Support

For issues or questions:

1. Check logs in logs/ directory
2. Review Prisma Studio: npm run prisma:studio
3. Check PostgreSQL and Redis are running
4. Verify environment variables

Production Deployment

Before deploying to production:

1. Update NODE_ENV=production
2. Generate secure JWT_SECRET
3. Configure production database
4. Setup Redis cluster
5. Enable HTTPS
6. Configure CORS properly
7. Setup monitoring and logging
8. Test all functionality

---

Status: Backend foundation is complete and ready for route implementation!

Created files: 14 core files Database entities: 13 Enums: 10 Achievements: 18 Modules: 3 Topics: 5