.ai

Imported from JAPV-X2612/TutorConnect-Backend (.ai/AGENTS.md). Install upstream with npx skills add JAPV-X2612/TutorConnect-Backend --skill .ai. Copyright stays with the author.

TutorConnect Backend — AI Agent Context

This file is the single source of truth for any AI agent (Claude, Gemini, GitHub Copilot, Cursor, etc.) working on the TutorConnect backend. Read it completely before generating or modifying any code.

📋 Project Description

TutorConnect is an on-demand tutoring and skills marketplace with a commission-per-completed-session business model. It connects learners with verified tutors in academic subjects and practical skills (programming, cooking, mechanics, languages, etc.).

👥 Development Team

🏗️ General Architecture

• Pattern: Modular monolith (NOT physically separated microservices)
• Backend: NestJS deployed on AWS ECS Fargate behind an Application Load Balancer (ALB)
• Frontend: React Native + Expo (APK for Android device)
• Authentication: Clerk as Identity Provider (IdP) — the backend only validates the JWT; it never issues it or manages passwords
• Database: PostgreSQL (AWS RDS in production, Docker locally)
• Cache: Redis (sessions, pub/sub for real-time messaging)
• Vector database: Pinecone (semantic tutor search)
• AI model: Claude API by Anthropic (natural language — HU-10, HU-11)
• Push notifications: Firebase
• File storage: AWS S3 (tutor certifications)
• Secrets: AWS Secrets Manager → exposed as environment variables in ECS Task Definitions

📦 System Modules

🗄️ Key Entities and Relationships

UserEntity (id: uuid, clerkId: unique+indexed, email, role: TUTOR|LEARNER, status)
├── TutorTopicEntity        (tutor FK → user, name)
├── TutorAvailabilityEntity (tutor FK → user, dayOfWeek, startTime, endTime)
├── TutorCertificationEntity (tutor FK → user, fileUrl, fileType, areaTitle)
├── TutorCourseEntity       (tutor FK, subject, price, duration, schedule JSON, modality)
├── LearnerPreferenceEntity (learner FK → user, topic FK → TutorTopicEntity)
├── ChatChannelEntity       (tutor FK, learner FK, unique(tutor, learner))
│   └── MessageEntity       (channel FK, sender FK → user, content, sentAt)
├── BookingEntity           (student FK → user, tutor FK, course FK, status, startTime)
│   ├── PaymentEntity       (booking FK, learner FK, amount, commissionRate, commissionAmount)
│   └── ReviewEntity        (booking FK, learner FK, tutor FK, rating 1-5, comment)

System Enums

🔑 Authentication Flow

1. The user authenticates on the frontend via Clerk
2. Clerk issues a signed JWT with the user's clerkId and role in the payload
3. The frontend attaches the JWT in the Authorization: Bearer <token> header
4. The backend validates the JWT using ClerkJwtGuard (via Clerk SDK)
5. The authenticated clerkId is read from req.user.clerkId — NEVER from query params, path params, or body

Available Guards (already implemented in src/modules/auth/)

// JWT validation only
@UseGuards(ClerkJwtGuard)
@Get('me')
getProfile(@Req() req: Request) { ... }

// JWT + role restriction
@UseGuards(ClerkJwtGuard, RoleGuard)
@Roles(UserRole.TUTOR)
@Get('dashboard/tutor')
getTutorDashboard(@Req() req: Request) { ... }

📁 Module File Structure

src/
  modules/
    <module>/
      <module>.module.ts
      <module>.controller.ts
      <module>.service.ts
      <module>.service.spec.ts
      entities/            ← subfolder only if 2+ entities
        <entity>.entity.ts
      dto/                 ← subfolder only if 3+ DTOs
        create-<entity>.dto.ts
        update-<entity>.dto.ts
        <entity>.dto.ts
      gateways/            ← only for WebSocket modules
        <module>.gateway.ts
  migrations/
    <Timestamp><MigrationName>.ts
  common/
    enums/
    decorators/
    guards/
  data-source.ts

Scaffolding Rules

• Flat structure per module until 3+ files of the same type justify a subfolder
• File names: kebab-case with type suffix (booking.service.ts, create-booking.dto.ts)
• Class names: PascalCase with type suffix (BookingService, CreateBookingDto)
• Do not duplicate entities across modules — always import from the owning module using TypeOrmModule.forFeature([Entity])

🗃️ Database Conventions

Migration Commands

# Generate migration
npx typeorm migration:generate src/migrations/MigrationName -d src/data-source.ts

# Run migrations
npx typeorm migration:run -d src/data-source.ts

⚠️ synchronize: true is forbidden outside the local environment — it can silently drop columns.

🧠 AI Features (MOD-BUS-003 — SearchModule)

AI functionality is isolated in the SearchModule. Do not add AI logic to any other module.

Main endpoint: POST /tutors/buscar-ia

🔄 Real-time Features

🛡️ Security Rules (non-negotiable)

• ❌ NEVER accept clerkId as a path param, query param, or request body — always extract from the JWT
• ❌ NEVER issue JWTs or manage passwords — Clerk is the sole identity source
• ❌ NEVER use synchronize: true in TypeORM outside the local environment
• ❌ NEVER commit .env — only .env.example with empty variable names
• ❌ NEVER hardcode credentials, API keys, or secrets — use environment variables
• ✅ ALWAYS apply ClerkJwtGuard to all protected endpoints
• ✅ ALWAYS use ValidationPipe({ whitelist: true, forbidNonWhitelisted: true }) globally

✅ Quality Standards

📝 Required JSDoc Format

/**
 * Brief, single-sentence description of the class or interface.
 *
 * @author Camilo Quintero, Jesús Pinzón, Laura Rodríguez, Santiago Díaz, Sergio Bejarano
 * @version 1.0
 * @since YYYY-MM-DD
 */

⚡ Required Environment Variables

# Database
DATABASE_URL=

# Clerk (authentication)
CLERK_SECRET_KEY=
CLERK_WEBHOOK_SECRET=

# Redis (cache and pub/sub)
REDIS_URL=

# Pinecone (vector search — MOD-BUS-003)
PINECONE_API_KEY=
PINECONE_INDEX_NAME=

# Claude API (AI — MOD-BUS-003)
ANTHROPIC_API_KEY=

# Firebase (push notifications)
FIREBASE_PROJECT_ID=
FIREBASE_PRIVATE_KEY=
FIREBASE_CLIENT_EMAIL=

# AWS S3 (tutor certifications)
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=
AWS_S3_BUCKET=

# Business configuration
SESIONES_META_SEMANAL=5