backend-context

Files (2)

• SKILL.md
• auth-context.md · references/

SKILL.md (first lines)

## Stack

| Technology | Version | Purpose |
|------------|---------|---------|
| Express.js | 5 | HTTP framework |
| TypeScript | 5 | Language |
| Prisma | 6 | ORM |
| MySQL | - | Database |
| Zod | 4 | Env validation |
| express-validator | 7 | Request validation |
| JWT (jsonwebtoken) | 9 | Authentication |
| Winston | 3 | Logging |
| Morgan | 1 | HTTP request logging |
| Multer | 2 | File uploads |
| Brevo | 3 | Transactional emails |
| Nodemailer | 7 | Email (fallback) |
| Jest + ts-jest | - | Testing |
| Supertest | 7 | HTTP testing |

**File Naming Example:**
- ✅ `sendAuthEmail.test.ts` (all tests with .test extencion)
- ✅ `createToken.ts` (common files use camel case)
- ✅ `auth.controller.ts` | `auth.route.ts` `auth.schema.ts` `auth.service.ts` (for each repositori spesification)
- ✅ `AuthMiddleware.ts` (Uper camel case for classes)
- ❌ `create-token.ts` (WRONG - do no separate be -)
- ❌ `sign-up-validation.spec.ts` | `sing-up-validation.ts`(WRONG )

## Scope Detection (ASK IF AMBIGUOUS)

| User Says | Action |
|-----------|--------|
| "a test", "one test", "new test", "add test" | Create ONE test() in existing spec |
| "comprehensive tests", "all tests", "test suite", "generate tests" | Create full suite |
| "create route", "create router" | Trigger `backend-router` skill and add it |
| "create schema", "add validation" | Trigger `backend-schema` skill and add it |

**Examples:**
- "Create a test for user sign-up" → ONE test only
- "Generate E2E tests for login page" → Full suite
- "Add a test to verify form validation" → ONE test to existing spec
- "create POST /login route” → ONE route 


## Directory Structure

```
backend/
├── prisma/                   # Database schema, migrations, seeds
│   ├── schema.prisma         # MySQL schema definition
│   ├── migrations/           # Prisma migration history
│   ├── seed.ts               # Database seeder
│   └── clear.ts              # Database cleanup script
├── src/
│   ├── index.ts              # Entry point — instantiates Server
│   ├── server.ts             # Server class (middlewares, routes, shutdown)
│   ├── config/               # App configuration (envs, prisma, logger, cors, email clients)
│   ├── routes/               # Route class definitions — mounted under /api/
│   ├── controllers/          # Request handlers for each domain
│   ├── auth/                 # Self-contained auth module (routes, controller, service, schema, tests)
│   ├── common/               # Shared code
│   │   ├── middleware/       # Auth, Role, validation, error handling, timeout
│   │   ├── schema/           # Global validation schemas
│   │   └── utils/            # Helpers (asyncHandler, createToken)
│   ├── email/                # Email templates (Brevo / Nodemailer)
│   ├── example/              # Reference module for new features
│   └── __test__/             # Integration / unit tests
├── logs/                     # Winston log output (gitignored)
├── docs/                     # Additional documentation
└── jest.config.js            # Jest + ts-jest config
```

## Architecture

The backend uses two architectural patterns:

**Repository pattern** — Self-contained modules under `src/` with own routes, controller, service, schema, and tests. Each repository owns its full vertical slice.

| Repository | Path | Description |
|------------|------|-------------|
| `auth` | `src/auth/` | Authentication, JWT, password flows — [details](references/auth-context.md) |

**Layered pattern** — Domains that share `src/routes/`, `src/controllers/` and `src/common/`. Currently used by the remaining modules while migrating to repository pattern.

| Domain | Routes | Controller |
|--------|--------|------------|
| projects | `src/routes/project.routes.ts` | `src/controllers/project.controller.ts` |
| events | `src/routes/event.routes.ts` | `src/controllers/event.controller.ts` |
| persons | `src/routes/person.routes.ts` | `src/controllers/person.controller.ts` |

**Request flow:**

```
Request → Middleware Chain → Route Class → Controller → Service → Prisma → MySQL
                                              ↓
                                         schema (express-validator)
```

**Layered responsibilities:**

| Layer | Responsibility | Location |
|-------|---------------|----------|
| Server | Bootstrap, middleware chain, graceful shutdown | `src/server.ts` |
| Routes | HTTP method + path + middleware stack per endpoint | `src/routes/`, `src/auth/auth.routes.ts` |
| Controller | Parse request, call service/prisma, format response | `src/controllers/`, `src/auth/auth.controller.ts` |
| Service | Business logic, reusable operations | `src/auth/auth.service.ts` |
| Schema | Request validation rules (express-validator) | `src/auth/auth.schema.ts`, `src/common/schema/` |
| Middleware | Cross-cutting: auth, roles, timeout, errors, logging | `src/common/middleware/` |
| Config | Singletons and env-validated settings | `src/config/` |

**Request lifecycle:**

1. `requestTimeout(30s)` wraps the request
2. Body parsers (`json`, `urlencoded`) with 10mb limit
3. CORS via `corsConfig`
4. Morgan HTTP logging
5. `Routes.init(app)` matches the endpoint
6. Route-level middleware chain (e.g. `authLimiter` → `validateSchema` → `authMiddleware` → controller)
7. Controller handles logic, returns response
8. Unmatched routes → `notFound` (404)

From davidleonmayor/proyecto-grado-unimayor, Apache-2.0.

More from davidleonmayor/proyecto-grado-unimayor