🌍 CleanTech SaaS — Smart RAEE IoT Platform

Plataforma SaaS completa para gestión de reciclaje de RAEE en entornos urbanos

CleanTech es una plataforma SaaS full-stack para la monitorización e incentivo del reciclaje de Residuos de Aparatos Eléctricos y Electrónicos (RAEE). El sistema implementa la arquitectura completa de un producto real: frontend web interactivo con simulación IoT, backend API REST con autenticación JWT, base de datos PostgreSQL persistente, y CI/CD automatizado para despliegue en producción.

🏗️ Arquitectura General

┌─────────────────────────────────────────────────────────────────┐
│                        CLEANTECH SAAS                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────────┐     ┌──────────────────────────────┐  │
│  │    FRONTEND (web/)   │     │     BACKEND API (api/)       │  │
│  │                      │     │                              │  │
│  │  TypeScript + Vite   │────▶│  Node.js + Express           │  │
│  │  TailwindCSS         │     │  JWT Authentication          │  │
│  │  Simulation IoT      │     │  Prisma ORM                  │  │
│  │  Dashboard UI        │     │  PostgreSQL Database         │  │
│  └─────────────────────┘     │  Redis Cache (opcional)       │  │
│                               │  Swagger API Docs             │  │
│                               └──────────────────────────────┘  │
│                                         │                        │
│                                         ▼                        │
│                               ┌──────────────────────────────┐  │
│                               │     INFRASTRUCTURA (AWS)      │  │
│                               │                              │  │
│                               │  EC2 + RDS + ElastiCache     │  │
│                               │  CloudFront + Route53        │  │
│                               │  Docker + GitHub Actions     │  │
│                               └──────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Las Tres Capas del Sistema

Capa	Tecnología	Descripción
1. Cliente (Frontend)	TypeScript, Vite, TailwindCSS	UI interactiva, simulación de sensores, dashboard
2. Servidor (API)	Node.js, Express, JWT, Prisma	Lógica de negocio, autenticación, validación
3. Datos	PostgreSQL 15, Redis 7	Persistencia, caché, migraciones

🛠️ Tecnologías

Frontend

TypeScript 5.x — Strict mode absoluto
Vite 5 — Build ultrarrápido y HMR
TailwindCSS 3 — Utility-first CSS
Vitest — Testing unitario con cobertura
Patrón Observable — Estado reactivo sin frameworks

Backend

Node.js 20 — Runtime LTS
Express 4 — Framework HTTP minimalista
Prisma ORM 5 — Type-safe database client
PostgreSQL 15 — Base de datos relacional
JWT — Autenticación stateless (access + refresh tokens)
Joi — Validación de schemas
Pino — Logger estructurado JSON
Swagger/OpenAPI — Documentación automática de API
Bcrypt — Hash de contraseñas
Helmet — Seguridad HTTP headers
CORS — Configuración restrictiva

Infraestructura

Docker + Docker Compose para desarrollo local
GitHub Actions — CI/CD automatizado
AWS — EC2, RDS, ElastiCache, CloudFront
Sentry — Error tracking (próximamente)

📁 Estructura del Monorepo

CleanTech/
├── api/                          # 🟢 Backend API
│   ├── prisma/
│   │   └── schema.prisma         # Esquema de base de datos
│   ├── src/
│   │   ├── index.ts              # Entry point del servidor
│   │   ├── config/               # Configuración centralizada
│   │   ├── controllers/          # Manejadores HTTP
│   │   │   ├── auth.controller.ts
│   │   │   ├── transaction.controller.ts
│   │   │   ├── reward.controller.ts
│   │   │   └── admin.controller.ts
│   │   ├── services/             # Lógica de negocio
│   │   │   ├── auth.service.ts
│   │   │   ├── transaction.service.ts
│   │   │   └── reward.service.ts
│   │   ├── middleware/           # Middleware Express
│   │   │   ├── auth.ts           # JWT authentication
│   │   │   ├── errorHandler.ts   # Error handling global
│   │   │   └── validate.ts       # Validación Joi
│   │   ├── routes/               # Definiciones de rutas
│   │   ├── utils/                # Utilidades
│   │   │   ├── logger.ts         # Pino logger
│   │   │   └── validation.ts     # Schemas Joi
│   │   └── database/
│   │       ├── client.ts         # Prisma singleton
│   │       └── seed.ts           # Datos de ejemplo
│   ├── tests/                    # Tests backend
│   ├── Dockerfile                # Container API
│   ├── package.json
│   └── tsconfig.json
│
├── web/                          # 🟣 Frontend Web
│   ├── src/                      # Código fuente TypeScript
│   ├── tests/                    # Tests frontend
│   ├── index.html                # HTML entry
│   ├── vite.config.ts
│   ├── package.json
│   └── tsconfig.json
│
├── shared/                       # 🟡 Tipos Compartidos
│   └── types/
│       └── index.ts              # Interfaces y tipos compartidos
│
├── docker-compose.yml            # Desarrollo local
├── README.md                     # Esta documentación
└── LICENSE (MIT)

🖥️ Frontend Web (`web/`)

El frontend es una aplicación web interactiva que simula un sistema IoT de reciclaje RAEE con:

Simulación de sensores HX711 con ruido gaussiano, deriva térmica y jitter
Dashboard analítico con métricas en tiempo real
Display LCD de estado del sistema
Sistema de recompensas con niveles (bronze → platinum)
Animaciones premium con scroll, contadores y parallax

Documentación detallada del frontend →

🖧 Backend API (`api/`)

API REST robusta con arquitectura en capas:

Stack

Express con middleware de seguridad (Helmet, CORS)
JWT con access tokens (15 min) y refresh tokens (7 días)
Prisma ORM para PostgreSQL con migraciones
Joi para validación server-side en todos los endpoints
Pino para logging estructurado JSON
Swagger UI disponible en /api/docs

Endpoints principales

Método	Endpoint	Descripción	Auth
POST	`/auth/register`	Registro de usuario	No
POST	`/auth/login`	Inicio de sesión	No
POST	`/auth/refresh`	Refrescar token	No
GET	`/auth/me`	Perfil usuario	JWT
PUT	`/auth/me`	Actualizar perfil	JWT
POST	`/api/transactions`	Registrar depósito RAEE	JWT
GET	`/api/transactions`	Historial (paginado)	JWT
GET	`/api/rewards`	Recompensas disponibles	JWT
POST	`/api/rewards/:id/redeem`	Canjear recompensa	JWT
GET	`/api/dashboard`	Dashboard usuario	JWT
GET	`/api/admin/dashboard`	Dashboard admin	Admin
GET	`/api/admin/users`	Listar usuarios	Admin
CRUD	`/api/admin/containers`	Gestionar contenedores	Admin
GET	`/health`	Health check	No

Documentación completa Swagger →

🔒 Autenticación y Seguridad

JWT Stateless

Access Token: 15 minutos de validez
Refresh Token: 7 días de validez
Almacenados en httpOnly cookies (producción) o Authorization header
En cada request protegido, el middleware authenticateToken verifica:
1. Token presente en header Authorization: Bearer <token>
2. Firma válida con JWT_ACCESS_SECRET
3. Token no expirado

Seguridad Adicional

Bcrypt con 10 rounds para hash de contraseñas
Rate limiting en login/register (5 intentos/15 min)
Helmet para HTTP headers de seguridad
CORS restrictivo por origen
Validación Joi en todos los inputs
Prepared statements via Prisma (previene SQL injection)
Validación de proximidad GPS (±50m del contenedor)

💾 Base de Datos

Esquema (Prisma ORM)

Users ──┐                  ┌── Containers
         │                  │
         ├── Transactions ──┘
         │
         └── UserRewards ── Rewards
         
Municipalities ── Containers

Modelos principales

User — Ciudadanos, admins, municipios (con soft delete)
Municipality — Municipios registrados en la plataforma
Container — Contenedores IoT con GPS y capacidad
Transaction — Depósitos de RAEE con validación de proximidad
Reward — Recompensas canjeables por tokens
UserReward — Historial de canjes
AuditLog — Trazabilidad de todas las operaciones

🐳 Docker

Desarrollo Local

# Iniciar todos los servicios (API + PostgreSQL + Redis)
docker-compose up -d

# Ejecutar migraciones
npm run migrate

# Poblar base de datos con datos demo
npm run seed

# Ver logs
docker-compose logs -f api

Estructura `docker-compose.yml`

Servicio	Puerto	Descripción
`api`	3000	Node.js API
`postgres`	5432	PostgreSQL 15
`redis`	6379	Redis 7 (caché)

🚀 Despliegue en Producción

AWS Stack

EC2 (t3.medium) — API Node.js con auto-scaling
RDS — PostgreSQL 15 managed
ElastiCache — Redis cluster
CloudFront — CDN frontend estático
Route53 — DNS management
ACM — SSL/TLS certificates

CI/CD (GitHub Actions)

Push/PR → Lint → Test (unit + integration) → Build → Deploy

Tests automáticos en cada push
Deploy a staging en PR merge
Deploy a producción en push a main
Rollback automático si health check falla

🧪 Testing

Frontend (Vitest)

31 tests unitarios + integración
Cobertura mínima: 80%
Flujo completo: sensor simulado → edge → state

Backend (Vitest)

Tests unitarios de servicios
Tests de lógica de negocio (tokens, niveles, GPS)
Tests de autenticación (JWT, bcrypt)
Cobertura mínima: 80%

# Frontend
cd web && npm run test

# Backend
cd api && npm run test

🗺️ Roadmap

Fase	Duración	Objetivos
Fase 1 (TFG)	✅ Completo	Frontend IoT simulado, documentación
Fase 2 (Actual)	Sem 1-2	API REST + PostgreSQL + Autenticación
Fase 3	Sem 3-4	Transacciones reales, recompensas, GPS
Fase 4	Sem 5-6	Admin dashboard, testing, Swagger
Fase 5	Sem 7-8	Docker, CI/CD, deploy AWS producción
Fase 6 (Futuro)	Próximo	MQTT real, Stripe, app mobile

Name		Name	Last commit message	Last commit date
Latest commit History 43 Commits
.github/workflows		.github/workflows
api		api
shared/types		shared/types
web		web
.directory		.directory
.gitignore		.gitignore
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json

Folders and files

Latest commit

History

Repository files navigation

🌍 CleanTech SaaS — Smart RAEE IoT Platform

📋 Índice

🏗️ Arquitectura General

Las Tres Capas del Sistema

🛠️ Tecnologías

Frontend

Backend

Infraestructura

📁 Estructura del Monorepo

🖥️ Frontend Web (web/)

🖧 Backend API (api/)

Stack

Endpoints principales

🔒 Autenticación y Seguridad

JWT Stateless

Seguridad Adicional

💾 Base de Datos

Esquema (Prisma ORM)

Modelos principales

🐳 Docker

Desarrollo Local

Estructura docker-compose.yml

🚀 Despliegue en Producción

AWS Stack

CI/CD (GitHub Actions)

🧪 Testing

Frontend (Vitest)

Backend (Vitest)

🗺️ Roadmap

📚 Referencias

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

🖥️ Frontend Web (`web/`)

🖧 Backend API (`api/`)

Estructura `docker-compose.yml`

Packages