Blog API - Node.js + TypeScript + PostgreSQL

Una API REST completa para un sistema de blog con autenticación, gestión de posts, comentarios y usuarios.

🏗️ Arquitectura

Este proyecto utiliza Feature-Based Architecture (Arquitectura Basada en Características), organizando el código por funcionalidades en lugar de por tipo de archivo.

Ventajas de esta arquitectura:

• ✅ Modularidad: Cada feature es independiente y autocontenida
• ✅ Escalabilidad: Fácil añadir nuevas features sin afectar las existentes
• ✅ Mantenibilidad: Código más fácil de entender y modificar
• ✅ Testing: Pruebas más sencillas por módulos aislados
• ✅ Team-friendly: Múltiples desarrolladores pueden trabajar en features distintas

🚀 Características

Core Features

• ✅ Autenticación JWT con refresh tokens
• ✅ CRUD completo de Posts con slugs únicos
• ✅ Sistema de comentarios con respuestas anidadas
• ✅ Gestión de usuarios con roles (USER/ADMIN)
• ✅ Sistema de tags
• ✅ Paginación y búsqueda
• ✅ Subida de imágenes (local o DigitalOcean Spaces)
• ✅ Envío de emails transaccionales (Brevo)

Arquitectura & Calidad

• ✅ TypeScript con strict mode
• ✅ Feature-Based Architecture
• ✅ Prisma ORM con migraciones
• ✅ Redis para caching
• ✅ Rate limiting
• ✅ Logging avanzado con Winston
• ✅ Health checks y monitoring
• ✅ Tests con Vitest
• ✅ Documentación API con Swagger
• ✅ Seeders con datos de prueba

Seguridad

• ✅ Helmet.js para headers de seguridad
• ✅ CORS configurado
• ✅ Validación de datos con Zod
• ✅ Password hashing con bcrypt
• ✅ Rate limiting por endpoint
• ✅ JWT con expiración

📦 Tecnologías

• Node.js + TypeScript - Runtime y lenguaje
• Express - Framework web
• PostgreSQL - Base de datos relacional
• Prisma - ORM moderno
• Zod - Validación de schemas
• JWT - Autenticación
• bcryptjs - Hash de contraseñas
• Helmet + CORS - Seguridad

📁 Estructura del Proyecto

node-api-blog/
├── src/
│   ├── features/                    # Módulos por funcionalidad
│   │   ├── auth/                   # 🔐 Autenticación
│   │   │   ├── auth.controller.ts
│   │   │   ├── auth.service.ts
│   │   │   ├── auth.routes.ts
│   │   │   └── index.ts
│   │   ├── posts/                  # 📝 Posts
│   │   ├── users/                  # 👤 Usuarios
│   │   └── comments/               # 💬 Comentarios
│   ├── shared/                      # Código compartido
│   │   ├── middleware/
│   │   │   ├── auth.middleware.ts
│   │   │   └── validation.middleware.ts
│   │   └── utils/
│   ├── lib/                         # Configuración de librerías
│   │   └── prisma.ts
│   ├── types/                       # Tipos TypeScript
│   │   └── index.ts
│   ├── app.ts                       # Configuración Express
│   └── index.ts                     # Punto de entrada
├── prisma/
│   └── schema.prisma
├── dist/                            # Código compilado
├── tsconfig.json
├── MIGRATION_GUIDE.md              # Guía de migración
└── NEXT_STEPS.md                   # Próximas mejoras

🛠️ Instalación

# 1. Clonar repositorio
git clone <repo-url>
cd node-api-blog

# 2. Instalar dependencias
npm install

# 3. Configurar variables de entorno
cp .env.example .env

# 4. Ejecutar migraciones
npm run db:migrate

# 5. Generar cliente Prisma
npm run db:generate

# 6. Poblar base de datos (opcional)
npm run db:seed

Variables de Entorno

# Server
PORT=3000
NODE_ENV=development

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/blog_db"

# JWT
JWT_SECRET=your-secret-key-here
JWT_EXPIRES_IN=7d

🚀 Comandos

# Desarrollo (con hot-reload)
npm run dev

# Compilar TypeScript
npm run build

# Producción
npm start

# Base de datos
npm run db:migrate      # Ejecutar migraciones
npm run db:generate     # Generar cliente Prisma
npm run db:studio       # Abrir Prisma Studio
npm run db:seed         # Poblar con datos de prueba

Endpoints de la API

Autenticación

• POST /api/auth/register - Registrar usuario
• POST /api/auth/login - Iniciar sesión
• GET /api/auth/me - Obtener usuario actual
• POST /api/auth/refresh - Renovar token

Posts

• GET /api/posts - Listar posts (con paginación, búsqueda, filtros)
• GET /api/posts/:slug - Obtener post por slug
• POST /api/posts - Crear post (autenticado)
• PUT /api/posts/:id - Actualizar post (autor/admin)
• DELETE /api/posts/:id - Eliminar post (autor/admin)
• GET /api/posts/author/:username - Posts por autor

Comentarios

• GET /api/comments/post/:postId - Comentarios de un post
• POST /api/comments/post/:postId - Crear comentario (autenticado)
• PUT /api/comments/:id - Actualizar comentario (autor/admin)
• DELETE /api/comments/:id - Eliminar comentario (autor/admin)
• GET /api/comments/user/:userId - Comentarios de un usuario

Usuarios

• GET /api/users - Listar usuarios (admin)
• GET /api/users/profile - Perfil actual (autenticado)
• GET /api/users/:id - Obtener usuario por ID
• GET /api/users/username/:username - Obtener usuario por username
• PUT /api/users/profile - Actualizar perfil (autenticado)
• PUT /api/users/change-password - Cambiar contraseña (autenticado)
• PUT /api/users/:id/role - Cambiar rol de usuario (admin)
• DELETE /api/users/:id - Eliminar usuario (admin)

Imágenes

• POST /api/images/upload - Subir imagen (autenticado)
• POST /api/images/upload-multiple - Subir múltiples imágenes (autenticado)
• PUT /api/images/avatar - Actualizar avatar (autenticado)
• DELETE /api/images/:filename - Eliminar imagen (autenticado)
• GET /api/images/list - Listar imágenes (admin)

🏛️ Arquitectura de Capas

Cada feature sigue el patrón de 3 capas:

1. Controller (Controlador)

• Maneja requests y responses HTTP
• Valida datos de entrada
• Llama al service apropiado
• Formatea las respuestas

2. Service (Servicio)

• Contiene la lógica de negocio
• Interactúa con la base de datos (Prisma)
• Independiente de HTTP
• Fácil de testear

3. Routes (Rutas)

• Define endpoints
• Aplica middlewares (auth, validación)
• Conecta rutas con controllers

Flujo de una petición:

Request → Route → Middleware → Controller → Service → Database
                                    ↓
Response ← Controller ← Service ←┘

Modelos de Datos

Usuario

• ID, email, username, firstName, lastName
• Password (hasheado), role (USER/ADMIN)
• Avatar, bio, timestamps

Post

• ID, title, slug, content, excerpt
• featuredImage, published, publishedAt
• Relación con autor y comentarios
• Sistema de tags

Comentario

• ID, content, timestamps
• Relación con autor y post
• Soporte para comentarios anidados (replies)

Tag

• ID, name, slug
• Relación many-to-many con posts

Autenticación

La API utiliza JWT para autenticación. Incluye el token en el header:

Authorization: Bearer <your-jwt-token>

Roles y Permisos

• USER: Puede crear posts, comentarios, gestionar su perfil
• ADMIN: Acceso completo, puede gestionar todos los recursos

Paginación

Los endpoints que devuelven listas soportan paginación:

GET /api/posts?page=1&limit=10

Respuesta:

{
  "posts": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 50,
    "pages": 5
  }
}

Búsqueda y Filtros

Posts

• ?search=término - Buscar en título, contenido y excerpt
• ?tag=slug-tag - Filtrar por tag
• ?author=userId - Filtrar por autor

Usuarios (admin)

• ?search=término - Buscar en email, username, nombre
• ?role=USER|ADMIN - Filtrar por rol

🧪 Testing (Próximamente)

Ver NEXT_STEPS.md para el plan de implementación de testing con Vitest.

🐳 Docker (Próximamente)

Ver NEXT_STEPS.md para la configuración de Docker y Docker Compose.

📖 Documentación API (Próximamente)

Swagger/OpenAPI disponible en /api/docs (por implementar).

🚧 Próximas Mejoras

Revisa NEXT_STEPS.md para ver el roadmap completo:

1. Database Seeders - Datos de prueba automáticos
2. Redis Cache - Mejora de rendimiento
3. Docker - Containerización completa
4. Testing - Pruebas unitarias e integración
5. Swagger - Autodocumentación interactiva

🤝 Contribución

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📝 Licencia

MIT

---

¿Migrado desde JavaScript? Revisa MIGRATION_GUIDE.md para entender los cambios.