QR Timeclock

QR Timeclock es una demo MVP full-stack pensada para modernizar el registro de entrada y salida de empleados en entornos de trabajo fisicos. El proyecto propone una alternativa ligera, verificable y facil de operar: los empleados escanean un codigo QR dinamico desde su telefono y el sistema registra el punch usando la hora del servidor como fuente de verdad.

Mas que una simple app de asistencia, el proyecto esta disenado como una solucion de producto. Combina una experiencia movil sencilla para empleados, una pantalla dedicada para mostrar el QR en el lugar de trabajo y una base administrativa para supervisar registros, validar eventos y construir flujos operativos mas robustos.

Problema

Muchas empresas pequenas y equipos operativos siguen dependiendo de procesos manuales o poco confiables para registrar asistencia: hojas de calculo, mensajes, relojes fisicos costosos o sistemas dificiles de adaptar.

Esto genera registros inconsistentes o manipulables, falta de visibilidad para administradores, procesos lentos para validar entradas y salidas, dependencia de hardware especializado y dificultad para saber si un registro ocurrio realmente en el lugar correcto y en el momento correcto.

QR Timeclock nace para explorar una solucion mas simple, accesible y controlada, usando herramientas web modernas y validacion desde el backend.

Solucion

La solucion propone un flujo directo: una pantalla ubicada en el lugar de trabajo muestra un QR que rota periodicamente, el empleado lo escanea desde una app movil y el backend valida el token antes de registrar el evento.

El sistema esta disenado alrededor de tres ideas clave:

• QR dinamico: reduce el riesgo de reutilizacion de codigos antiguos.
• Timestamp del servidor: evita depender de la hora del dispositivo del empleado.
• Validacion centralizada: mantiene las reglas de negocio en el backend, no en el cliente.

El resultado es un MVP que demuestra como construir un sistema de asistencia con una arquitectura clara, escalable y orientada a producto.

Que permite hacer

Con este MVP, el sistema permite:

• Mostrar un codigo QR rotativo en una pantalla fija del lugar de trabajo.
• Escanear el QR desde una experiencia movil para empleados.
• Registrar entradas y salidas usando la hora oficial del servidor.
• Validar tokens QR dentro de una ventana de tiempo controlada.
• Consultar el estado general del sistema mediante un endpoint de salud.
• Sentar la base para un panel administrativo de supervision.
• Separar responsabilidades entre frontend movil, display QR, dashboard admin y API.

Arquitectura

El proyecto esta organizado como un monorepo full-stack, separando cada parte del sistema por responsabilidad:

• Backend API: servicio construido con FastAPI para manejar validaciones, reglas de negocio, endpoints y futura integracion con base de datos.
• Employee App: aplicacion web/PWA orientada al empleado, enfocada en el flujo de escaneo y registro de asistencia.
• QR Display App: aplicacion para una pantalla fija que muestra el QR rotativo que los empleados deben escanear.
• Admin Dashboard: panel administrativo para supervisar registros, revisar actividad y eventualmente gestionar empleados, ubicaciones y reportes.
• Base de datos: PostgreSQL como base para almacenar empleados, eventos de asistencia, tokens, ubicaciones y auditoria.
• Scripts y configuracion local: comandos de instalacion, ejecucion, testing y Docker Compose para facilitar el desarrollo local.

Stack tecnico

• Vue 3
• Vite
• Vuetify
• PWA/mobile-first
• Python
• FastAPI
• Pytest
• API REST
• PostgreSQL
• Docker Compose
• Variables de entorno con .env
• Monorepo
• Validacion server-side
• Testing automatizado para endpoints base

Enfoque de ingenieria

El proyecto esta planteado con un enfoque pragmatico: construir primero una base clara, verificable y extensible antes de agregar complejidad innecesaria.

Algunas decisiones destacables:

• Monorepo: mantiene backend, frontends y scripts bajo una misma estructura de trabajo.
• Separacion de modulos: evita mezclar la experiencia del empleado, el display QR y el panel administrativo.
• Hora del servidor como fuente de verdad: decision critica para sistemas de asistencia.
• Ventana de rotacion del QR de 30 a 60 segundos: reduce el riesgo de reutilizacion indebida.
• Timezone fijo en America/Panama: mantiene consistencia operativa en el MVP.
• Testing desde el inicio: comienza por el endpoint /health como base de validacion.
• Docker Compose: facilita un entorno local reproducible con API y PostgreSQL.

Valor del MVP

Como MVP, QR Timeclock demuestra una solucion completa a un problema operativo real, sin intentar resolver todo desde el primer dia. El valor esta en validar el flujo principal: generar, mostrar, escanear, validar y registrar.

El proyecto muestra capacidad para pensar mas alla de la interfaz: modela un problema de negocio concreto, define limites claros entre cliente y servidor, prioriza seguridad basica y confiabilidad del registro, propone una experiencia simple para usuarios no tecnicos y deja una arquitectura preparada para crecer.

Es una demo ideal para portafolio porque combina producto, backend, frontend, arquitectura e intencion tecnica en un caso de uso facil de entender.

Posibles extensiones

El MVP puede evolucionar hacia autenticacion para empleados y administradores, gestion de empleados, turnos y ubicaciones, reportes por rango de fechas, exportacion a CSV, integracion con nomina, geolocalizacion opcional, auditoria de eventos sospechosos, roles y permisos, notificaciones por incidencias, modo offline limitado y panel analitico con metricas de puntualidad y asistencia.