elearning/.agent/workflows/setup.md

---
description: How to setup the backend development environment
---

# Setup Development Environment

Follow these steps to setup the E-Learning Platform backend with TypeScript and TSOA on your local machine.

---

## Prerequisites

- Node.js 18+ and npm
- Docker and Docker Compose
- Git

---

## Step 1: Clone Repository

```bash
git clone <repository-url>
cd e-learning/Backend
```

---

## Step 2: Install Dependencies

// turbo
```bash
npm install
```

// turbo
Install TypeScript and TSOA:
```bash
npm install -D typescript @types/node @types/express ts-node nodemon
npm install tsoa swagger-ui-express
```

---

## Step 3: Initialize TypeScript

// turbo
Create `tsconfig.json`:
```bash
npx tsc --init
```

Update `tsconfig.json`:
```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

---

## Step 4: Configure TSOA

Create `tsoa.json`:
```json
{
  "entryFile": "src/app.ts",
  "noImplicitAdditionalProperties": "throw-on-extras",
  "controllerPathGlobs": ["src/controllers/**/*.controller.ts"],
  "spec": {
    "outputDirectory": "public",
    "specVersion": 3,
    "securityDefinitions": {
      "jwt": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "routes": {
    "routesDir": "src/routes",
    "middleware": "express",
    "authenticationModule": "./src/middleware/auth.ts"
  }
}
```

---

## Step 5: Setup Environment Variables

Copy example env file:
```bash
cp .env.example .env
```

Edit `.env`:
```bash
# Application
NODE_ENV=development
PORT=4000
APP_URL=http://localhost:4000

# Database
DATABASE_URL=postgresql://postgres:12345678@localhost:5432/elearning_dev

# MinIO/S3
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=admin
S3_SECRET_KEY=12345678
S3_BUCKET_COURSES=courses
S3_BUCKET_VIDEOS=videos
S3_BUCKET_DOCUMENTS=documents
S3_BUCKET_IMAGES=images
S3_BUCKET_ATTACHMENTS=attachments

# JWT
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRES_IN=24h

# Email (Mailhog)
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_FROM=noreply@elearning.local
```

---

## Step 4: Start Docker Services

// turbo
```bash
docker compose up -d
```

This starts:
- PostgreSQL (port 5432)
- MinIO (ports 9000, 9001)
- Mailhog (ports 1025, 8025)
- Adminer (port 8080)

---

## Step 6: Run Database Migrations

// turbo
```bash
npx prisma migrate dev
```

---

## Step 7: Seed Database

// turbo
```bash
npx prisma db seed
```

This creates:
- Default roles (Admin, Instructor, Student)
- Test users
- Sample categories
- Sample courses

---

## Step 8: Generate TSOA Routes

// turbo
```bash
npm run tsoa:gen
```

This generates:
- Routes in `src/routes/tsoa-routes.ts`
- Swagger spec in `public/swagger.json`

---

## Step 9: Start Development Server

// turbo
```bash
npm run dev
```

Server will start at http://localhost:4000

---

## Step 10: Verify Setup

// turbo
Test health endpoint:
```bash
curl http://localhost:4000/health
```

// turbo
Test login:
```bash
curl -X POST http://localhost:4000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'
```

---

## Access Services

| Service | URL | Credentials |
|---------|-----|-------------|
| **Backend API** | http://localhost:4000 | - |
| **API Docs (Swagger)** | http://localhost:4000/api-docs | - |
| **MinIO Console** | http://localhost:9001 | admin / 12345678 |
| **Mailhog UI** | http://localhost:8025 | - |
| **Adminer** | http://localhost:8080 | postgres / 12345678 |

---

## Development Commands

```bash
# Start dev server (TypeScript)
npm run dev

# Build TypeScript
npm run build

# Generate TSOA routes and Swagger
npm run tsoa:gen

# Run tests
npm test

# Run linter
npm run lint

# Format code
npm run format

# Generate Prisma Client
npx prisma generate

# View database in Prisma Studio
npx prisma studio

# Reset database (WARNING: deletes all data)
npx prisma migrate reset
```

---

## Troubleshooting

### Port Already in Use
```bash
# Find process using port
lsof -i :4000

# Kill process
kill -9 <PID>
```

### Database Connection Error
```bash
# Check if PostgreSQL is running
docker ps | grep postgres

# Check logs
docker logs elearning-postgres

# Restart PostgreSQL
docker restart elearning-postgres
```

### Prisma Client Error
```bash
# Regenerate client
npx prisma generate

# Clear node_modules
rm -rf node_modules
npm install
```

---

## Checklist

- [ ] Node.js 18+ installed
- [ ] Docker installed and running
- [ ] Repository cloned
- [ ] Dependencies installed
- [ ] `.env` file configured
- [ ] Docker services running
- [ ] Database migrated
- [ ] Database seeded
- [ ] Dev server running
- [ ] Health check passing
- [ ] Login test successful

---

## Next Steps

- Read [Backend Development Rules](../.agent/rules.md)
- Follow [Create API Endpoint](./create-api-endpoint.md) workflow
- Review [Agent Skills](../docs/agent_skills_backend.md)