HabitForge

---

Sobre el Proyecto

HabitForge es una aplicacion full-stack para el seguimiento de habitos personales con un enfoque unico en accountability social. Permite a los usuarios crear habitos, registrar su progreso diario, mantener rachas (streaks) y compartir su avance con un partner de responsabilidad.

El proyecto nacio de la necesidad de una herramienta que no solo rastree habitos, sino que incorpore mecanismos de presion social positiva para mantener la consistencia. A diferencia de otras apps de habitos, HabitForge pone el foco en la relacion entre dos personas que se comprometen mutuamente a cumplir sus metas.

Problema que resuelve

• Las apps de habitos convencionales dependen solo de la voluntad individual
• La mayoria no ofrece mecanismos de accountability social
• Los algoritmos de streaks suelen ser basicos y no manejan edge cases (limites de mes/anio)
• Falta de APIs bien documentadas para integraciones futuras

Caracteristicas

MVP Implementado

• Autenticacion completa - Registro, login y perfil con JWT + Passport
• CRUD de habitos - Crear, listar, actualizar, eliminar y reordenar habitos
• Sistema de check-ins - Check-in individual, batch y undo con validacion de duplicados
• Algoritmo de streaks - Calculo inteligente con soporte para limites de mes y anio
• Dashboard analitico - Resumen diario, calendario de completado y estadisticas por periodo
• Accountability Partners - Sistema de invitaciones por codigo unico
• Notificaciones programadas - Recordatorios diarios via cron job (9 AM)
• UI Neomorfica - Frontend single-page con Tailwind CSS y Alpine.js
• API RESTful versionada - Prefijo /api/v1 con respuestas estandarizadas

Detalles Tecnicos

• Validacion declarativa con class-validator y class-transformer
• Manejo centralizado de excepciones con filtro global
• Interceptor de transformacion para respuestas consistentes ({ success, data, timestamp })
• Decorador personalizado @CurrentUser para acceso al usuario autenticado
• Indices de base de datos optimizados para consultas frecuentes
• Constraint UNIQUE en check-ins para prevenir duplicados a nivel de DB

Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                        AppModule (Root)                         │
│  ConfigModule.forRoot() | TypeOrmModule.forRoot() | Schedule    │
└──────────┬──────────┬──────────┬──────────┬──────────┬──────────┘
           │          │          │          │          │
    ┌──────┴──┐ ┌─────┴───┐ ┌───┴────┐ ┌───┴───┐ ┌───┴────────┐
    │  Auth   │ │ Habits  │ │CheckIns│ │Streaks│ │ Dashboard  │
    │ Module  │ │ Module  │ │ Module │ │Module │ │  Module    │
    ├─────────┤ ├─────────┤ ├────────┤ ├───────┤ ├────────────┤
    │Controller│ │Controller│ │Controller│ │       │ │ Controller │
    │ Service │ │ Service │ │ Service│ │Service│ │  Service   │
    │JWT Strat│ │         │ │        │ │       │ │            │
    │Local St.│ │         │ │        │ │       │ │            │
    └────┬────┘ └────┬────┘ └───┬────┘ └───┬───┘ └─────┬──────┘
         │          │          │          │           │
    ┌────┴────┐ ┌───┴────┐ ┌───┴───┐ ┌───┴───┐ ┌────┴─────┐
    │  User   │ │ Habit  │ │CheckIn│ │Streak │ │ Habit    │
    │ Entity  │ │ Entity │ │Entity │ │Entity │ │ CheckIn  │
    └─────────┘ └────────┘ └───────┘ └───────┘ │ Streak   │
                                                └──────────┘
    ┌───────────────────┐  ┌───────────────────────────────┐
    │  Notifications    │  │         Common                │
    │  Module           │  │  HttpExceptionFilter          │
    │  (Cron: 9 AM)     │  │  TransformInterceptor         │
    └───────────────────┘  │  @CurrentUser Decorator       │
                           └───────────────────────────────┘

Flujo de Datos

Cliente HTTP
    │
    ▼
ValidationPipe (whitelist + transform)
    │
    ▼
Controller (rutas, guards, decoradores)
    │
    ▼
Service (logica de negocio)
    │
    ▼
TypeORM Repository (acceso a datos)
    │
    ▼
SQLite / PostgreSQL

Para documentacion detallada de la arquitectura, ver docs/ARCHITECTURE.md

Stack Tecnologico

Capa	Tecnologia	Proposito
Runtime	Node.js 22	Entorno de ejecucion
Framework	NestJS 10	Framework backend modular
Lenguaje	TypeScript 5.3	Tipado estatico
ORM	TypeORM 0.3	Mapeo objeto-relacional
DB (dev)	SQLite (better-sqlite3)	Base de datos local
DB (prod)	PostgreSQL 16	Base de datos produccion
Auth	Passport + JWT	Autenticacion stateless
Validacion	class-validator	Validacion declarativa
Scheduler	@nestjs/schedule	Cron jobs
Frontend	Tailwind CSS + Alpine.js	UI neomorfica reactiva
Testing	Jest + Supertest	Unit + E2E tests
Contenedor	Docker	Despliegue

Instalacion

Prerrequisitos

• Node.js >= 22
• npm >= 9
• Docker y Docker Compose (opcional, para PostgreSQL y Redis)

Configuracion rapida

# 1. Clonar el repositorio
git clone https://github.com/ronalc90/habit-forge.git
cd habit-forge

# 2. Instalar dependencias
npm ci

# 3. Configurar variables de entorno
cp .env.example .env
# Editar .env con tus valores

# 4. Ejecutar en modo desarrollo (SQLite por defecto)
npm run start:dev

# 5. Abrir el frontend
open http://localhost:3000

Con Docker (PostgreSQL + Redis)

# Levantar servicios de infraestructura
docker-compose up -d

# Configurar .env para apuntar a PostgreSQL
# DB_HOST=localhost, DB_PORT=5432, etc.

# Ejecutar la app
npm run start:dev

Variables de Entorno

Variable	Descripcion	Default	Requerida
DB_HOST	Host de PostgreSQL	localhost	No*
DB_PORT	Puerto de PostgreSQL	5432	No*
DB_USERNAME	Usuario de PostgreSQL	habitforge	No*
DB_PASSWORD	Password de PostgreSQL	-	No*
DB_DATABASE	Nombre de la base de datos	habitforge.sqlite	No
JWT_SECRET	Clave secreta para tokens JWT	-	Si
JWT_EXPIRATION	Tiempo de expiracion del token	7d	No
PORT	Puerto de la aplicacion	3000	No
NODE_ENV	Entorno de ejecucion	development	No
REDIS_HOST	Host de Redis	localhost	No
REDIS_PORT	Puerto de Redis	6379	No
CORS_ORIGIN	Origen permitido para CORS	*	No

*En modo desarrollo se usa SQLite y no se requiere PostgreSQL.

API Documentation

Todos los endpoints usan el prefijo /api/v1. Las respuestas siguen el formato estandarizado:

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-04-10T12:00:00.000Z"
}

Salud

Metodo	Endpoint	Descripcion	Auth
GET	/api/v1/health	Health check (Docker, Kubernetes, ALB)	No

Autenticacion

Metodo	Endpoint	Descripcion	Auth
POST	/api/v1/auth/register	Registrar nuevo usuario	No
POST	/api/v1/auth/login	Iniciar sesion	No
GET	/api/v1/auth/profile	Obtener perfil del usuario	JWT

Habitos

Metodo	Endpoint	Descripcion	Auth
POST	/api/v1/habits	Crear un habito	JWT
GET	/api/v1/habits	Listar todos los habitos	JWT
GET	/api/v1/habits?active=true	Listar habitos activos	JWT
GET	/api/v1/habits/:id	Obtener un habito por ID	JWT
PATCH	/api/v1/habits/:id	Actualizar un habito	JWT
DELETE	/api/v1/habits/:id	Eliminar un habito	JWT
POST	/api/v1/habits/reorder	Reordenar habitos	JWT

Check-ins

Metodo	Endpoint	Descripcion	Auth
POST	/api/v1/check-ins	Registrar check-in	JWT
POST	/api/v1/check-ins/batch	Check-in masivo	JWT
DELETE	/api/v1/check-ins/:habitId	Deshacer check-in	JWT
GET	/api/v1/check-ins/today	Check-ins de hoy	JWT
GET	/api/v1/check-ins/range	Check-ins por rango de fechas	JWT
GET	/api/v1/check-ins/status/:habitId	Estado de check-in	JWT

Dashboard

Metodo	Endpoint	Descripcion	Auth
GET	/api/v1/dashboard/today	Resumen del dia	JWT
GET	/api/v1/dashboard/calendar	Datos de calendario	JWT
GET	/api/v1/dashboard/stats	Estadisticas por periodo	JWT

Para documentacion completa con ejemplos curl, ver docs/API.md

Estructura del Proyecto

habit-forge/
├── src/
│   ├── auth/                    # Modulo de autenticacion
│   │   ├── dto/                 # DTOs: RegisterDto, LoginDto, AuthResponseDto
│   │   ├── guards/              # JwtAuthGuard, LocalAuthGuard
│   │   ├── strategies/          # JwtStrategy, LocalStrategy (Passport)
│   │   ├── auth.controller.ts   # Rutas: register, login, profile
│   │   ├── auth.service.ts      # Logica: hashing, validacion, JWT
│   │   └── auth.module.ts
│   ├── habits/                  # Modulo de habitos
│   │   ├── dto/                 # CreateHabitDto, UpdateHabitDto, ReorderDto
│   │   ├── habits.controller.ts # CRUD + reorder
│   │   ├── habits.service.ts    # Logica de negocio
│   │   └── habits.module.ts
│   ├── check-ins/               # Modulo de check-ins
│   │   ├── dto/                 # CreateCheckInDto, BatchDto, DateRangeDto
│   │   ├── check-ins.controller.ts
│   │   ├── check-ins.service.ts # Check-in, undo, batch, consultas
│   │   └── check-ins.module.ts
│   ├── streaks/                 # Modulo de rachas
│   │   ├── streaks.service.ts   # Algoritmo de calculo de rachas
│   │   └── streaks.module.ts
│   ├── dashboard/               # Modulo de dashboard
│   │   ├── dto/                 # DashboardQueryDto (period, date)
│   │   ├── dashboard.controller.ts
│   │   ├── dashboard.service.ts # Resumen, calendario, estadisticas
│   │   └── dashboard.module.ts
│   ├── notifications/           # Modulo de notificaciones
│   │   ├── notifications.service.ts  # Cron diario + mock push
│   │   └── notifications.module.ts
│   ├── common/                  # Utilidades compartidas
│   │   ├── decorators/          # @CurrentUser
│   │   ├── filters/             # HttpExceptionFilter global
│   │   ├── interceptors/        # TransformInterceptor
│   │   └── dto/                 # PaginationDto
│   ├── database/
│   │   ├── entities/            # User, Habit, CheckIn, Streak, AccountabilityPartner
│   │   └── migrations/          # Migracion inicial
│   ├── app.module.ts            # Modulo raiz
│   └── main.ts                  # Bootstrap de la aplicacion
├── test/
│   └── app.e2e-spec.ts          # Tests E2E del flujo completo
├── public/
│   └── index.html               # Frontend neomorfico (SPA)
├── docs/                        # Documentacion tecnica
├── .github/workflows/           # CI/CD con GitHub Actions
├── Dockerfile                   # Build multi-stage
├── docker-compose.yml           # PostgreSQL + Redis
├── package.json
└── tsconfig.json

Decisiones Tecnicas

Decision	Alternativa	Razon
NestJS sobre Express puro	Express, Fastify	Arquitectura modular, DI nativa, decoradores, ecosistema de modulos
TypeORM sobre Prisma	Prisma, Sequelize	Decoradores nativos con NestJS, Active Record + Data Mapper, migraciones
SQLite para desarrollo	PostgreSQL local, Docker	Zero-config, archivo unico, ideal para desarrollo rapido
JWT + Passport	Session-based auth	Stateless, escalable, multiples estrategias (local + jwt)
Neomorfismo para UI	Material, Bootstrap	Diferenciacion visual, experiencia tactil, innovacion en UX
Algoritmo incremental para streaks	Recalculo completo	O(1) en check-in vs O(n), con recalculo completo como fallback en undo

Para ADRs detallados, ver docs/DECISIONS.md

Testing

El proyecto cuenta con 57 tests unitarios y 21 tests E2E (78 tests en total):

# Ejecutar tests unitarios
npm test

# Ejecutar con cobertura
npm run test:cov

# Ejecutar tests E2E (requiere PostgreSQL)
npm run test:e2e

# Ejecutar en modo watch
npm run test:watch

Distribucion de Tests

Modulo	Tests	Tipo
AuthController	6	Unit
HabitsController	10	Unit
CheckInsService	13	Unit
StreaksService	17	Unit
DashboardService	11	Unit
App E2E Flow	21	E2E
Total	78	-

Estrategia de Testing

• Unit tests: Servicios y controladores aislados con mocks de repositorios
• E2E tests: Flujo completo auth -> habits -> check-ins -> streaks -> dashboard
• Cobertura: Caso feliz + validaciones + errores + edge cases (limites de mes/anio)

Despliegue

Docker

# Construir imagen
docker build -t habitforge .

# Ejecutar contenedor
docker run -p 3000:3000 \
  -e JWT_SECRET=tu-clave-secreta \
  -e DB_DATABASE=habitforge.sqlite \
  habitforge

Railway

# Instalar Railway CLI
npm i -g @railway/cli

# Login y deploy
railway login
railway init
railway up

Para instrucciones detalladas de despliegue, ver docs/DEPLOYMENT.md

Roadmap

• MVP: Auth + Habits + Check-ins + Streaks + Dashboard
• Frontend neomorfico con Tailwind + Alpine.js
• Sistema de accountability partners
• Notificaciones programadas (cron)
• Tests unitarios y E2E
• Notificaciones push reales (Firebase Cloud Messaging)
• Sistema de logros y gamificacion
• Exportacion de datos (CSV, PDF)
• App movil (React Native)
• Integracion con wearables (Apple Health, Google Fit)
• Modo oscuro en UI neomorfica

Autor

Desarrollado por Ronald - GitHub

Licencia

Este proyecto esta bajo la Licencia MIT. Ver LICENSE para mas detalles.