Proyecto del Club Taws (ESPOL). Aplicación web que automatiza el control de acceso al local del club mediante reconocimiento facial, el registro de jornadas de limpieza y la gestión de incidencias/multas, con notificaciones automáticas por WhatsApp.
La especificación completa de requisitos está en
docs/ERS_SERGI_v1.1.pdf.
| Persona | Rol |
|---|---|
| Javier Gutiérrez | Líder |
| José Adrián | Co-líder |
| Andrés Saltos | Desarrollador |
| Nahin Cevallos | Desarrollador |
| Victor Morales | Desarrollador |
| Melissa Suarez | Desarrollador |
Arquitectura de tres capas desacopladas (ver sección 7 del ERS):
| Capa | Tecnología | Carpeta |
|---|---|---|
| Frontend | React + Vite + TypeScript + Shadcn/ui | frontend/ |
| Backend / API | Node.js + Express + TypeScript | backend/ |
| Reconocimiento facial | MediaPipe (cliente) + DeepFace (microservicio Python) | facial-service/ |
| Base de datos | PostgreSQL | — |
| Notificaciones | WhatsApp Business API | — |
| Infraestructura | Docker / Docker Compose | docker-compose.yml |
Durante desarrollo se puede ejecutar el frontend por separado con Vite, y en producción se sigue el patrón de 2-step build del ERS: el frontend se compila y luego es servido estáticamente por el backend (Express). La base de datos y los servicios auxiliares quedan levantados con Docker Compose para un despliegue reproducible en el servidor del club.
-
Clonar el repo y crear un archivo
.enven la raíz a partir de.env.example:cp .env.example .env
-
Ajustar los valores sensibles, especialmente
POSTGRES_PASSWORD,JWT_SECRETy los tokens de WhatsApp. -
Levantar los servicios con Docker Compose:
docker compose up --build
-
Verificar que el backend responde en
http://localhost:3000/healthy que el facial-service responde enhttp://localhost:8000/health.curl http://localhost:3000/health curl http://localhost:8000/health
El frontend se mantiene en desarrollo con
npm run devdesde la carpetafrontend/cuando se necesita inspección rápida. En producción, el ERS contempla el patrón de 2-step build y el backend sirve el bundle compilado.
El
facial-serviceya está implementado con su Dockerfile y queda integrado dentro de la red de Docker Compose del proyecto. El servicio expone/health,/embeddingsy/match, y puede levantarse con el entorno completo del repo sin requerir pasos adicionales fuera de la configuración del.env.
db: PostgreSQL 16.backend: API Node.js, depende dedby se conecta afacial-servicemedianteFACIAL_SERVICE_URL.facial-service: servicio Python base para reconocimiento facial.db-backup: contenedor con cron para respaldos automáticos diarios de la base de datos (RNF-DIS-03).
El servicio db-backup monta el directorio local ./backups y ejecuta un cron
que realiza un pg_dump diario según BACKUP_SCHEDULE (por defecto 0 2 * * *).
Los archivos generados quedan en:
./backups/Este directorio es de almacenamiento local del entorno y no debe subirse a Git. Los respaldos son datos sensibles y deben mantenerse fuera del repositorio.
Si quieres ajustar la frecuencia, modifica BACKUP_SCHEDULE en el .env de la
raíz y reinicia el servicio:
docker compose up -d --force-recreate db-backupPara verificar que el backup funciona en este momento, puedes ejecutar una prueba manual desde la raíz del proyecto:
docker compose exec db-backup sh -lc "PGPASSWORD=sergi pg_dump -h db -U sergi -d sergi -Fc > /backups/manual-test.dump && ls -l /backups"Si genera un archivo .dump, la copia de seguridad está funcionando correctamente.
Para restaurar desde un respaldo:
ls -l backups
# ejemplo de restauración
pg_restore -U sergi -d sergi backups/sergi-YYYY-MM-DD.dumpSi el despliegue se hace en el servidor del club, este mismo patrón puede dejarse como servicio del sistema de forma permanente; por ahora el compose lo deja operativo y reproducible dentro del repo, manteniendo los backups fuera del control de versiones.
La verificación necesaria para cerrar el issue es la siguiente:
docker compose up --build
docker compose ps
curl http://localhost:3000/health
docker compose exec backend sh -lc "wget -qO- http://facial-service:8000/health"
docker compose exec db-backup sh -lc "PGPASSWORD=sergi pg_dump -h db -U sergi -d sergi -Fc > /backups/manual-test.dump && ls -l /backups"Con esta validación se confirma que:
db,backendyfacial-servicelevantan con Docker Compose;- el backend responde en
/health; - el backend puede comunicarse con
facial-servicedentro de la red interna; - la copia de seguridad de PostgreSQL genera archivos
.dumpcorrectamente.
En desarrollo, el frontend puede ejecutarse por separado con npm run dev
si se necesita inspección rápida; la producción sigue el patrón de 2-step
build del ERS, donde el frontend se compila y luego es servido por el backend.
Cada subcarpeta (frontend/, backend/, facial-service/) tiene su propio
README con instrucciones específicas de desarrollo. Las piezas que aún no
están implementadas se mantienen como trabajo pendiente del issue de
infraestructura correspondiente.
- Cada tarea se gestiona como un Issue en GitHub, etiquetado por módulo
(
RF-BIO,RF-ACC,RF-LIM,RF-INC,RF-NOT,RF-AUD,infra) y por prioridad (prioridad-alta,prioridad-media,prioridad-baja). - Crear una rama por issue (
feature/<modulo>-<descripcion-corta>), abrir un Pull Request haciamainy vincularlo al issue correspondiente. - Antes de mergear, revisar que el PR no rompa el build de
frontend/ni debackend/.
El modelo de datos preliminar (entidades, atributos y relaciones) está documentado en la sección 6 y el Anexo B del ERS.