api-meparqueo

Backend central de MeParqueo: API REST + WebSockets construida con NestJS que conecta los sensores IoT de los parqueaderos con la app móvil y el panel de administración.

Parte del ecosistema MeParqueo

MeParqueo es un sistema IoT de parqueo inteligente en tiempo real (Montería, Colombia).

Repo	Descripción	Acceso
app-meparqueo	App móvil React Native para conductores	Público
api-meparqueo (este repo)	Backend NestJS: API central, tiempo real y webhook de sensores	Público
nodo-meparqueo	Firmware C++ del sensor ESP32 (LoRaWAN)	Privado
web-meparqueo	Frontend web	Privado
landing-meparqueo	Landing page	Privado
survey-meparqueo	Encuestas y validación	Privado

✨ Características

• API REST versionada bajo api/v1, con respuestas normalizadas (interceptor global) y filtro global de excepciones.
• Autenticación JWT con roles ADMIN, OWNER y USER (guards + decorador @Auth), registro/login y acceso anónimo por clientId para la app móvil.
• Parqueaderos: CRUD admin, historial de estados y búsqueda de cercanos con filtros (disponibilidad, rango de precio, servicios, métodos de pago), distancia caminando vía Google Maps Distance Matrix con fallback Haversine.
• Webhook IoT (POST /parking-lot/status): recibe el uplink_message.decoded_payload de los nodos LoRaWAN y actualiza estado y disponibilidad del parqueadero.
• Tiempo real con Socket.IO: middleware de autenticación JWT y emisión de eventos por rol (updateEstatus a admins, parkingUpdateStatus a usuarios).
• Nodos sensores: registro y gestión (código, versión, vinculación a parqueadero).
• Usuarios: ubicaciones, historial de búsquedas, parqueaderos visitados recientemente, reportes de parqueaderos y feedback con calificación.
• Dashboard: estadísticas de uso, crecimiento y comportamiento; configuración remota de la app (versión y banner).
• Imágenes con proveedor intercambiable: Cloudinary (por defecto) o AWS S3; se sirven con transformación w_500,f_auto,q_auto.
• Documentación interactiva en /docs (Stoplight Elements) y /docs-swagger (Swagger UI).
• Logging estructurado con nestjs-pino.

🛠️ Stack

• NestJS 11 + TypeScript (Node 22)
• Prisma 6 + PostgreSQL
• Socket.IO (@nestjs/websockets)
• Passport + JWT, bcrypt
• Cloudinary / AWS S3 (SDK v3)
• Google Maps Distance Matrix API
• nestjs-pino, Swagger + Stoplight Elements
• Husky + lint-staged · deploy con GitHub Actions (SSH + PM2)

📁 Estructura del proyecto

api-meparqueo/
├── .github/workflows/   # CI/CD: deploy a dev y prod vía SSH + PM2
├── .husky/              # Hooks de git (pre-commit, pre-push)
├── prisma/              # schema.prisma: modelos de datos (PostgreSQL)
└── src/
    ├── core/            # PrismaService y scripts de seed
    ├── decorators/      # @ResponseMessage para mensajes de respuesta
    ├── lib/             # ConfigLoader, logger, filtros, interceptores y docs
    ├── modules/         # Dominio: auth, parking-lot, node, user, report,
    │                    #   feedback, config, cloud-storage, google/maps, socket
    └── types/           # Tipos de configuración y extensiones de Express

🚀 Desarrollo local

Requisitos: Node 22.14+, PostgreSQL.

npm install
cp .env.example .env    # completa las variables
npx prisma generate
npx prisma db push      # sincroniza el esquema con la BD
npx prisma db seed      # opcional: crea el usuario admin inicial
npm run dev             # API en http://localhost:3000/api/v1

Otros scripts: npm run build, npm run start:prod, npm run lint, npm run format, npm test.

Variables de entorno (ver .env.example, solo nombres): LOG_LEVEL, PORT, DATABASE_URL, JWT_SECRET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_S3_BUCKET, CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, CLOUDINARY_API_SECRET, GOOGLE_MAPS_API_KEY, GOOGLE_MAPS_API_URL. El código también lee CLIENT_URL (origen permitido para WebSockets), que no está en .env.example.

👥 Hecho por bambai-labs

Desarrollado por el equipo de bambai-labs.