Propuesta técnica

Backend — Aplicación de Noticias de Proyectos

Documento confidencial · Versión para cliente

Introducción

Este documento describe el plan de desarrollo del backend para una plataforma híbrida: red social y periódico centrada en noticias y proyectos cercanos. Incluye arquitectura hexagonal, flujos de publicación con verificación por IA y aprobación administrativa, y tecnologías acordadas (React Native para la app móvil, backend con API REST).

Nos encargaremos del backend de forma integral: arquitectura hexagonal, API, base de datos, autenticación, integración con servicios de IA para verificación de contenido, almacenamiento de archivos, pruebas, CI/CD y despliegue en la nube.

Visión del proyecto: red social y periódico

El sistema combina red social y periódico: los usuarios cargan proyectos cercanos, pueden crear noticias según su rol, y el contenido pasa por verificación con IA y/o aprobación de un administrador antes de publicarse.

Proyectos cercanos

Los usuarios cargan y comparten proyectos cercanos (iniciativas, obras, eventos de su zona). Estos proyectos son contenido de la red social y contexto para las noticias.

Tipos de usuario y publicación

Periodistas verificados: usuarios reconocidos que pasan verificación y pueden publicar noticias directamente. Resto de usuarios: pueden crear noticias pero requieren verificación con tokens de IA y luego aprobación de un administrador para que la noticia se publique.

Verificación con IA

Se utilizarán tokens de IA para revisar que las noticias enviadas por usuarios no verificados cumplan criterios de calidad y coherencia. El resultado de la verificación alimenta el flujo de aprobación.

Aprobación administrativa

Un administrador revisa y aprueba las noticias que pasaron la verificación de IA (o las rechaza). Solo el contenido aprobado se publica en el “periódico” visible para todos.

Resumen: Red social (proyectos cercanos, usuarios creadores) + periódico (contenido curado). Dos vías de publicación: periodista verificado → publicación directa; usuario estándar → verificación IA → aprobación admin → publicación.

Uso de React Native para la aplicación móvil

La aplicación móvil (lectura de noticias, carga de proyectos cercanos, creación de noticias por usuarios) se desarrollará con React Native. La elección se justifica por el uso extendido en la industria y los beneficios que aporta al proyecto:

Adopción por empresas: Muchas empresas ya usan React Native en producción (Meta/Facebook, Microsoft, Shopify, Discord, Bloomberg, entre otras), lo que garantiza un ecosistema maduro, documentación y soluciones a problemas comunes.
Un solo código para iOS y Android: Se mantiene una base de código compartida, reduciendo coste y tiempo de desarrollo y de evolución de la app en ambas plataformas.
Rendimiento y experiencia nativa: Compila a componentes nativos, ofreciendo una experiencia fluida y acceso a APIs del dispositivo (cámara, geolocalización, almacenamiento local) necesarias para proyectos cercanos y noticias.
Mantenibilidad y contratación: Al ser una tecnología muy demandada, es más fácil encontrar desarrolladores y mantener el proyecto a largo plazo.

Arquitectura hexagonal (Ports & Adapters)

El backend se desarrollará aplicando arquitectura hexagonal: el núcleo del dominio (lógica de negocio, reglas de publicación, verificación) queda aislado de los detalles técnicos; la comunicación con el exterior se hace mediante puertos (interfaces) y adaptadores (implementaciones concretas).

Ventajas para este proyecto: independencia de frameworks y bases de datos, pruebas unitarias del dominio sin infraestructura, y posibilidad de cambiar o añadir adaptadores (otra API, otro proveedor de IA, otro almacenamiento) sin reescribir la lógica de negocio.

Diagrama: aplicación del patrón hexagonal en el proyecto

flowchart TB subgraph Entrada["Puertos/Adaptadores de entrada"] REST[REST API] Panel[Panel web admin] end subgraph Nucleo["Núcleo (dominio)"] Services[Servicios de aplicación] Reglas[Reglas: publicación, verificación, aprobación] end subgraph Salida["Puertos/Adaptadores de salida"] PG[(PostgreSQL)] Redis[(Redis)] S3[S3 / almacenamiento] IA[Proveedor IA] end REST --> Services Panel --> Services Services --> Reglas Services --> PG Services --> Redis Services --> S3 Services --> IA

Entrada: La API REST y el panel web son adaptadores que envían peticiones al núcleo (casos de uso: crear noticia, aprobar, cargar proyecto, etc.).
Núcleo: Contiene la lógica de publicación (periodista verificado vs usuario estándar), orquestación de verificación IA y flujo de aprobación administrativa.
Salida: PostgreSQL, Redis, S3 y el proveedor de IA son adaptadores que el núcleo usa a través de puertos (repositorios, clientes de IA, almacenamiento), sin depender de implementaciones concretas.

Estructura del proyecto y funcionamiento

Visión de alto nivel: app móvil (React Native), backend con arquitectura hexagonal, panel admin y flujos de publicación diferenciados.

flowchart LR A[App React Native] B[Backend API] C[Panel admin] A -->|Noticias, proyectos, publicar| B C -->|Aprobar, gestionar| B B -->|Publica, datos| A

App (React Native) → Usuarios leen noticias, cargan proyectos cercanos, y según su rol crean noticias (periodista verificado: publica directo; usuario: envía a verificación IA y aprobación).
Backend (hexagonal) → API REST para la app y el panel; núcleo de dominio con reglas de publicación, integración con IA para verificación y persistencia en PostgreSQL/Redis/S3.
Panel admin → Revisión y aprobación de noticias pendientes, gestión de usuarios (verificación de periodistas), categorías y contenido.

Eficiencia de carga y lectura offline

Bandera de última noticia: El endpoint expondrá una bandera (timestamp o versión) de la última noticia publicada. La app podrá consultar solo este valor para decidir si hay contenido nuevo.
Caché local y lectura sin conexión: La aplicación contará con caché local (p. ej. almacenamiento en dispositivo) que permitirá a los usuarios leer noticias aunque estén desconectados, usando la última copia descargada.
Carga condicional: La carga será eficiente porque solo se pedirán noticias al API cuando la última noticia que el usuario tiene registrada sea más antigua que la bandera del endpoint. Si la bandera no ha cambiado, la app usará el caché y no consumirá ancho de banda ni tiempo de red innecesariamente.

Además se mantendrán consultas optimizadas, caché en servidor (Redis), tiempos de respuesta bajos y una experiencia rápida tanto en el editor web como en la app.

Especificaciones técnicas acordadas

Node.js con TypeScript (2+ años)

NestJS (Node.js + TypeScript)

PostgreSQL — modelo, índices, optimización

Redis — caché y colas (BullMQ o similar)

API REST bien diseñada e implementada

JWT (access + refresh tokens)

Validación, sanitización y seguridad API

Tests unitarios e integración (Jest)

Git flow, PRs, conventional commits

CI/CD (GitHub Actions o similar)

Despliegue con Dokku

S3 o equivalente para archivos/imágenes

Variables de entorno y gestión de secretos

Trabajo autónomo como único backend

React Native (app móvil)

Arquitectura hexagonal

Verificación de contenido con IA (tokens)

Framework del API y despliegue con Dokku

Se compararon los principales frameworks para construir el API de esta plataforma (red social + periódico, arquitectura hexagonal, verificación IA, colas, múltiples roles). El despliegue en producción se realizará con Dokku (PaaS autoalojado tipo Heroku, despliegue por git push, soporte para PostgreSQL, Redis y variables de entorno).

Comparativa de frameworks para este API

Framework	Lenguaje	Fortalezas	Ajuste a este proyecto
NestJS	Node.js / TypeScript	Arquitectura por módulos e inyección de dependencias, ideal para hexagonal; TypeScript (tipado, refactor seguro); ecosistema: TypeORM/Prisma, Bull/BullMQ, class-validator, JWT; mismo lenguaje para API y workers.	Muy alto: encaja con hexagonal, flujos complejos (aprobación, IA), colas y validación; Dokku soporta Node nativamente.
Laravel	PHP	Desarrollo rápido, Eloquent, colas y caché con Redis, Sanctum/Passport, ecosistema maduro.	Alto: buen CRUD y colas; hexagonal requiere más disciplina; PHP menos habitual en equipos que ya usan React Native/Node.
FastAPI	Python	Async, documentación OpenAPI automática, Pydantic; fuerte en integración con ML/IA en el mismo lenguaje.	Medio: excelente para APIs puras; el proyecto solo consume un API de IA externa (HTTP), no corre modelos; menos convención para CRUD + workflows que NestJS/Laravel.
Go (Gin / Fiber)	Go	Rendimiento, binario único, concurrencia nativa; muy bueno en Dokku.	Medio: más boilerplate para auth, validación, colas y flujos de aprobación; menos “baterías incluidas” para este tipo de API.

Elección: NestJS (Node.js + TypeScript)

Se utilizará NestJS con Node.js y TypeScript para este API porque encaja de forma directa con la arquitectura hexagonal que queremos aplicar: los módulos y la inyección de dependencias permiten definir puertos (interfaces) en el núcleo e inyectar adaptadores (repositorios PostgreSQL, cliente de IA, almacenamiento S3) sin acoplar la lógica de negocio al framework. El tipado de TypeScript reduce errores y facilita el mantenimiento para un desarrollador que trabaja solo en el backend. NestJS ofrece soporte nativo para colas (Bull/BullMQ con Redis), validación con DTOs y class-validator, guards para JWT y roles, y una estructura clara por dominios (noticias, proyectos, usuarios, aprobaciones), lo que acelera la implementación de flujos como “verificación IA → aprobación admin” y la distinción entre periodistas verificados y usuarios estándar. La integración con proveedores de IA es trivial (llamadas HTTP desde servicios del núcleo). Por último, el despliegue con Dokku es sencillo (buildpack Node, Procfile, variables de entorno para BD y Redis), y el mismo runtime sirve tanto para el API como para los workers que procesen colas de verificación o notificaciones.

Dokku: Se usará Dokku como plataforma de despliegue. Permite despliegue por git push, gestión de aplicaciones en contenedores, add-ons o vinculación de PostgreSQL y Redis, y configuración de dominios y SSL. Compatible con el stack NestJS + Node y con pipelines de CI/CD (p. ej. GitHub Actions) que construyan y desplieguen contra el servidor Dokku.

Base de datos: modelo y desarrollo

El backend utilizará PostgreSQL como motor principal. El modelo soporta red social + periódico: usuarios que cargan proyectos cercanos, noticias con flujo de verificación IA y aprobación administrativa, y roles que permiten periodistas verificados (publicación directa) frente a usuarios que requieren aprobación. A continuación, tablas y diagrama entidad-relación.

Tablas del modelo

Tabla	Descripción y campos principales
`roles`	Roles del sistema: admin, editor, verified_journalist (periodista verificado, publica directo), user (requiere aprobación). Columnas: `id`, `name`, `slug`, timestamps.
`users`	Usuarios. Columnas: `id`, `name`, `email`, `password` (hash), `role_id` (FK), `email_verified_at`, `remember_token`, timestamps. El rol determina si puede publicar directo o debe pasar por aprobación.
`projects`	Proyectos cercanos cargados por usuarios. Campos: `id`, `user_id` (FK), `name`, `slug`, `description`, `location` (o lat/lng), `status`, timestamps. Contenido propio de la red social.
`categories`	Categorías/tópicos para clasificar noticias. Columnas: `id`, `name`, `slug`, `parent_id` (opcional), timestamps.
`news`	Noticias con flujo de publicación. Columnas: `id`, `title`, `slug`, `excerpt`, `body`, `category_id` (FK), `user_id` (autor), `project_id` (FK opcional), `status` (draft, pending_ai_review, pending_approval, published, rejected), `ai_verified_at`, `ai_verification_result` (o JSON), `approved_by` (FK user, admin), `approved_at`, `published_at`, timestamps.
`comments`	Comentarios en noticias. Columnas: `id`, `news_id` (FK), `user_id` (FK), `body`, `parent_id` (respuestas), timestamps.
`media`	Archivos/imágenes (polimórfico: noticia o proyecto). Columnas: `id`, `path`, `url`, `type`, `mediaable_id`, `mediaable_type`, `order`, timestamps.
`refresh_tokens`	Tokens de refresco JWT. Columnas: `id`, `user_id` (FK), `token` (hash), `expires_at`, `revoked_at`, timestamps.
`password_reset_tokens`	Tokens para restablecer contraseña (forgot/reset). Columnas: `id`, `user_id` (FK), `token` (hash o aleatorio), `expires_at`, `used_at`, timestamps.
`Profile`	Perfil de usuario (1:1). Columnas: `id`, `userId` (FK UNIQUE), `firstName`, `lastName`, `address`, `avatar`, `lastConnectionAt`, `lastNewsDownloadedId` (FK News), `lastCommentId` (FK Comment), `lastSearch`, timestamps. Usado por panel admin y app.

Diagrama entidad-relación

Usuarios con roles (admin, editor, verified_journalist, user); proyectos cercanos subidos por usuarios; noticias con flujo de estado (IA + aprobación); categorías, comentarios y medios. El diagrama se imprime correctamente en PDF.

erDiagram ROLES ||--o{ USERS : has USERS ||--o{ PROJECTS : uploads CATEGORIES ||--o{ NEWS : classifies USERS ||--o{ NEWS : writes PROJECTS ||--o{ NEWS : linked_to NEWS ||--o{ COMMENTS : has USERS ||--o{ COMMENTS : writes NEWS ||--o{ MEDIA : attachments PROJECTS ||--o{ MEDIA : attachments USERS ||--o{ REFRESH_TOKENS : tokens USERS ||--o{ PASSWORD_RESET_TOKENS : reset_tokens USERS ||--|| PROFILE : has PROFILE |o--o| NEWS : last_news PROFILE |o--o| COMMENTS : last_comment ROLES { int id PK string name string slug } USERS { int id PK string name string email string password int role_id FK date created_at date updated_at } PROJECTS { int id PK int user_id FK string name string slug string location } CATEGORIES { int id PK string name string slug int parent_id FK } NEWS { int id PK string title string slug string body int category_id FK int user_id FK int project_id FK string status date approved_at int approved_by FK } COMMENTS { int id PK int news_id FK int user_id FK string body } MEDIA { int id PK string path string url string mediaable_type int mediaable_id } REFRESH_TOKENS { int id PK int user_id FK string token date expires_at } PASSWORD_RESET_TOKENS { int id PK int user_id FK string token date expires_at date used_at } PROFILE { int id PK int userId FK,UK string firstName string lastName string address string avatar date lastConnectionAt int lastNewsDownloadedId FK int lastCommentId FK string lastSearch date created_at date updated_at }

Respaldo de la base de datos

Se mantendrá un sistema de respaldo automático para garantizar la integridad y recuperación de los datos:

Respaldo programado: copia de seguridad de la base de datos cada 12 horas (por ejemplo 00:00 y 12:00), con retención configurable.
Respaldo por evento: además, se ejecutará un respaldo cada vez que se publique una noticia nueva, para minimizar pérdida de contenido reciente en caso de incidencia.

Los respaldos se almacenarán en un almacenamiento seguro (por ejemplo S3 o equivalente) y se documentará el procedimiento de restauración.

Desarrollo con NestJS y PostgreSQL

El API se desarrollará con NestJS (Node.js + TypeScript) y PostgreSQL, tal como se justifica en la sección anterior. A continuación, aspectos de eficiencia y capacidades del stack elegido.

Análisis de eficiencia del API con NestJS

Cómo el stack NestJS + TypeORM/Prisma + Redis se traduce en eficiencia y mantenibilidad para este API:

Criterio	Impacto en eficiencia / Por qué esta tecnología
TypeORM/Prisma + relaciones	Eager loading y relaciones bien definidas evitan N+1 en listados de noticias (con categoría, autor, proyecto). Menos round-trips a la BD y respuestas del API más rápidas.
Redis como caché y colas (BullMQ)	Caché de respuestas (listados, bandera de última noticia) con TTL; colas BullMQ para verificación IA, procesamiento de imágenes o notificaciones en segundo plano sin bloquear la petición HTTP.
Índices y consultas en PostgreSQL	Índices en `published_at`, `category_id`, `status` y slugs. Búsquedas full-text opcionales. Planes de ejecución optimizables.
Serialización y DTOs	DTOs y class-transformer permiten un formato de respuesta controlado y consistente, reduciendo tamaño de payload y tiempo de parsing en la app React Native.
Guards y rate limiting	Guards de NestJS para JWT y roles; throttling por IP o usuario para evitar sobrecarga y mantener tiempos de respuesta estables.
Bandera “última noticia” en el API	Endpoint ligero (p. ej. `GET /api/v1/news/last-updated`) que devuelve solo timestamp o versión. La app compara con su caché y solo pide listado completo cuando hay novedades.

Módulos e inyección de dependencias — Estructura por dominios (noticias, proyectos, usuarios, aprobaciones) y puertos inyectables para adaptadores (BD, IA, S3), alineado con arquitectura hexagonal.

TypeORM/Prisma y migraciones — Modelos y relaciones alineados con el ER; migraciones versionadas para evolucionar el esquema sin romper entornos; eager loading para evitar N+1.

Seguridad y validación — class-validator en DTOs, sanitización de entradas, guards JWT y por roles; refresh tokens almacenados de forma segura en refresh_tokens.

Colas y caché — BullMQ con Redis para jobs (verificación IA, notificaciones, procesamiento de imágenes); caché en Redis para listados y bandera de última noticia.

Almacenamiento de archivos — Integración con S3 (o compatible) mediante adaptadores; medios asociados a noticias y proyectos según el modelo ER.

Testing y despliegue — Jest para pruebas unitarias e integración; mocks de puertos para probar el núcleo hexagonal; CI/CD con GitHub Actions y despliegue con Dokku (git push, PostgreSQL y Redis vinculados).

Plan de desarrollo por fases

1 Configuración inicial y arquitectura

Proyecto. Inicializar con NestJS (Node.js + TypeScript). Estructura por módulos/dominios (noticias, proyectos, usuarios, categorías, aprobaciones) alineada con arquitectura hexagonal.

Git. Repositorio con Git flow, ramas main, develop y feature branches. Conventional commits y protección de ramas con PRs obligatorios.

Entorno. Gestión de variables con .env y validación en arranque (p. ej. @nestjs/config o similar). Secretos fuera del código.

2 Base de datos PostgreSQL

Modelado. Diseño del esquema según el modelo ER (usuarios con roles, proyectos cercanos, noticias con flujo de aprobación/IA, categorías, comentarios, medios). Migraciones para versionado del esquema.

Índices. Índices en claves foráneas, fechas y campos de búsqueda/filtrado para listados de noticias por categoría.

Optimización. Consultas eficientes, evitando N+1; paginación en listados; revisión de planes de ejecución cuando sea necesario.

3 Redis: caché y colas

Caché. Uso de Redis para caché de respuestas (listados de noticias, perfiles) con TTL y estrategia de invalidación al crear/actualizar contenido.

Colas. BullMQ con Redis para trabajos en segundo plano: verificación IA, envío de notificaciones, procesamiento de imágenes. Workers desacoplados del API (mismo runtime NestJS).

4 API REST y seguridad

Diseño REST. Recursos claros (noticias, proyectos cercanos, categorías, usuarios, aprobaciones), códigos HTTP correctos, versionado de API (ej. /api/v1/). Documentación con Swagger/OpenAPI.

Validación y sanitización. DTOs con class-validator y class-transformer, sanitización de entradas para evitar inyecciones. Throttling (rate limiting) en endpoints públicos.

Seguridad. Headers de seguridad (CORS, Helmet), buenas prácticas OWASP aplicadas al backend.

Verificación con IA. Integración con proveedor de IA (tokens) para revisar noticias enviadas por usuarios no verificados; resultado almacenado en el flujo de estados y disponible para el administrador en la aprobación.

5 Autenticación JWT

Tokens. Access token (corta duración) y refresh token (almacenado en refresh_tokens, rotación opcional). Endpoints de login, refresh y logout.

Protección de rutas. Guards/middlewares que validen JWT y roles/permisos para acceso a noticias, categorías y recursos de usuario.

6 Almacenamiento de archivos (S3 o equivalente)

Servicio de almacenamiento. Integración con S3 (o compatible) para imágenes y adjuntos de noticias y proyectos cercanos; tabla media polimórfica (noticia, proyecto).

Flujo. Subida firmada o mediante API, almacenamiento de URLs en BD, política de eliminación y permisos coherente con el resto del sistema.

7 Pruebas (unitarias e integración)

Unitarias. Tests de servicios, validadores y lógica de negocio con mocks de repositorios y dependencias externas (Jest o PHPUnit según stack).

Integración. Tests de endpoints críticos (auth, noticias, proyectos, flujo de aprobación, verificación IA) con BD y Redis de prueba o contenedores. Cobertura mínima acordada para núcleo hexagonal y adaptadores.

8 CI/CD y despliegue

CI. GitHub Actions (o similar): lint, tests y build en cada PR. Branch protection que exija checks en verde antes de merge.

CD. Despliegue con Dokku: git push al servidor, buildpack Node, Procfile, PostgreSQL y Redis vinculados (add-ons o servicios externos). Variables y secretos en Dokku; pipeline opcional con GitHub Actions para desplegar contra el servidor Dokku.

9 Documentación y cierre

Documentación. README con setup local, variables necesarias y cómo ejecutar tests. API documentada (Swagger/OpenAPI) accesible en entorno de staging.

Entrega. Repositorio ordenado, convenciones de commits y PRs aplicadas, y capacidad de trabajar de forma autónoma hasta la conclusión del proyecto.

Resumen

El proyecto es una plataforma híbrida: red social y periódico. Los usuarios cargan proyectos cercanos y pueden crear noticias; los periodistas verificados publican directamente, y el resto de usuarios pasan por verificación con tokens de IA y aprobación de un administrador. La app móvil se desarrolla con React Native y el backend con arquitectura hexagonal (ports & adapters), API REST, PostgreSQL, Redis, S3 e integración con proveedores de IA.

El desarrollo se organiza en las fases descritas, con eficiencia, respaldos de BD (cada 12 h y al publicar), tests, Git flow, CI/CD y despliegue en la nube. El modelo de datos incluye roles (admin, editor, verified_journalist, user), proyectos cercanos, noticias con estados de flujo (pendiente_revision_ia, pendiente_aprobacion, publicada) y campos de verificación IA y aprobación.