CRUD MVC con Lucky y Angular

Aplicación web desarrollada bajo el patrón arquitectónico Modelo-Vista-Controlador (MVC) que implementa un sistema integral de Autenticación (Login) y un módulo protegido para la gestión de usuarios (CRUD completo: Crear, Leer, Actualizar y Eliminar).

El sistema cuenta con seguridad de doble capa: protección perimetral en cliente mediante Guards e interceptores HTTP en Angular, y validación estricta a nivel de servidor con Tokens JWT, Bcrypt y filtros de autorización en Lucky Framework.

---

📑 Tabla de Contenidos

1. 📹 Video Demostrativo
2. ✨ Características del Proyecto
3. 🏛️ Arquitectura MVC y Flujo del Tech Stack
4. 🔒 Seguridad y Encriptación de Contraseñas
5. 🛠️ Tecnologías Utilizadas (Tech Stack)
6. 📁 Estructura del Repositorio
7. 🚀 Instalación y Puesta en Marcha
8. 🔑 Credenciales de Prueba

---

📹 Video Demostrativo

---

✨ Características del Proyecto

[x] Autenticación Robusta: Flujo de inicio de sesión con generación de tokens JWT firmados (create.cr y auth.service.ts).

[x] Rutas Protegidas (Doble Capa):

• Frontend: authGuard y adminGuard impiden el acceso a rutas sin token o sin rol de administrador.
• Backend: Api::Auth::RequireAuthToken en api_action.cr rechaza solicitudes no autorizadas en cada endpoint del CRUD.

[x] CRUD Completo de Usuarios:

• Create (Crear): Formulario para registrar nuevos usuarios con validación de datos (users.ts y create.cr).
• Read (Leer): Listado general reactivo y visualización individual de detalles con modal SweetAlert2 (index.cr y read.cr).
• Update (Actualizar): Modo de edición dinámico reutilizando el formulario de entrada (update.cr).
• Delete (Eliminar): Eliminación controlada de registros en base de datos (delete.cr).

[x] Control de Acceso Basado en Roles (RBAC): Separación de privilegios entre usuarios regulares y administradores (user.cr).

[x] Encriptación de Contraseñas: Algoritmo de hashing seguro (Bcrypt) mediante Authentic en sign_up_user.cr, evitando el almacenamiento de contraseñas en texto plano.

---

🏛️ Arquitectura MVC y Flujo del Tech Stack

El sistema implementa de forma rigurosa la separación de responsabilidades del patrón Modelo-Vista-Controlador (MVC) desacoplado en dos capas modernas:

El Flujo de una Petición Protegida

sequenceDiagram
    autonumber
    actor Usuario
    participant V as Vista (Angular UI)
    participant G as Guards / Interceptor
    participant C as Controlador (Lucky Action)
    participant M as Modelo (Avram ORM)
    participant DB as PostgreSQL

    Usuario->>V: Ingresa credenciales y envía Login
    V->>C: POST /api/sign_ins (email, password)
    C->>M: SignInUser.run() valida hash con Bcrypt
    M-->>C: Usuario autenticado válido
    C-->>V: Retorna JWT Token + Datos de usuario
    V->>V: Almacena Token en LocalStorage

    Note over Usuario,V: Intento de acceder a la sección protegida (/users)
    Usuario->>V: Navega a /users
    V->>G: authGuard verifica presencia de Token
    G-->>V: Acceso autorizado en UI

    V->>G: authInterceptor adjunta Header Bearer Token
    G->>C: GET /api/users (Authorization: Bearer <token>)
    C->>C: ApiAction valida firma de JWT y rol Admin
    C->>M: UserQuery.new realiza consulta
    M->>DB: SELECT * FROM users
    DB-->>M: Registros de usuarios
    M->>C: UserSerializer procesa datos (omite password)
    C-->>V: Respuesta JSON 200 OK con usuarios
    V-->>Usuario: Renderiza tabla CRUD de usuarios

---

🔒 Seguridad y Encriptación de Contraseñas

En este proyecto se utilizó Bcrypt, el estándar de la industria recomendado sobre algoritmos obsoletos como MD5 o SHA-1:

1. Hashing Unidireccional con Salt: Al registrar un usuario en sign_up_user.cr, el shard Authentic ejecuta:

   Authentic.copy_and_encrypt(password, to: encrypted_password)
   

2. Protección en Base de Datos: En el modelo user.cr, la columna en PostgreSQL se define como column encrypted_password : String. El valor original en texto plano nunca se persiste.
3. Serialización Segura: En user_serializer.cr, el campo encrypted_password está estrictamente excluido para garantizar que ningún hash viaje hacia el cliente.
4. Verificación en Login: En sign_in_user.cr, la contraseña ingresada se procesa contra el salt y hash almacenados; si coinciden, se emite un JSON Web Token (JWT) mediante user_token.cr.

---

🛠️ Tecnologías Utilizadas (Tech Stack)

Backend (API REST MVC)

• Crystal Language: Lenguaje compilado con sintaxis inspirada en Ruby y rendimiento equivalente a C.
• Lucky Framework (v1.5.0): Framework web fullstack fuertemente tipado que previene errores en tiempo de compilación.
• Avram ORM: Mapeo objeto-relacional seguro contra inyecciones SQL.
• Authentic & JWT: Sistema de hashing Bcrypt y gestión de tokens de sesión.

Frontend (Single Page Application)

• Angular (v22): Framework empresarial para aplicaciones web.
• Angular Signals: Manejo reactivo de estado para listas de usuarios y formularios.
• Angular Router & Guards: Control de acceso perimetral (CanActivateFn).
• HTTP Client & Interceptors: Inyección automática de tokens Bearer en cabeceras.
• SweetAlert2: Alertas y modales interactivos para visualización de detalles y confirmaciones.

Base de Datos e Infraestructura

• PostgreSQL: Sistema de gestión de bases de datos relacional.
• Docker & Docker Compose: Contenedores para base de datos y entorno de ejecución.

---

📁 Estructura del Repositorio

forgeworks/
│
├── forgeworks_api/                      # ⚙️ BACKEND (Lucky Framework MVC)
│   ├── config/                          # Configuración de base de datos y servidor
│   ├── db/
│   │   ├── migrations/                  # Migraciones de base de datos
│   │   └── seed/                        # Semillas de datos iniciales
│   └── src/
│       ├── actions/                     # 🎮 CONTROLADORES (Actions)
│       │   ├── api_action.cr            # Base controller (AuthToken & RequireAdmin)
│       │   └── api/
│       │       ├── sign_ins/create.cr   # Endpoint de Login (POST /api/sign_ins)
│       │       └── users/               # Endpoints del CRUD (/api/users)
│       ├── models/                      # 🧠 MODELOS (Entidades Avram)
│       │   ├── user.cr                  # Modelo de Usuario y Roles
│       │   └── user_token.cr            # Generación y validación de JWT
│       ├── operations/                  # Lógica de Negocio y Validaciones
│       │   ├── sign_in_user.cr          # Verificación de credenciales
│       │   ├── sign_up_user.cr          # Creación y hashing de passwords
│       │   └── update_user.cr           # Actualización de datos
│       └── serializers/                 # 👁️ VISTAS JSON
│           └── user_serializer.cr       # Formateo de respuesta sin campos sensibles
│
├── forgeworks-web/                      # 🎨 FRONTEND (Angular)
│   └── src/app/
│       ├── core/
│       │   ├── guards/                  # 🛡️ Protección de Rutas
│       │   │   ├── auth.guard.ts        # Bloquea navegación a usuarios no autenticados
│       │   │   └── admin.guard.ts       # Valida rol administrativo
│       │   ├── interceptors/
│       │   │   └── auth.interceptor.ts  # Inyecta Bearer token en cada request HTTP
│       │   └── services/
│       │       ├── auth.service.ts      # Manejo de sesión y LocalStorage
│       │       └── user.service.ts      # Consumo de endpoints CRUD
│       └── pages/                       # 👁️ VISTAS (Componentes UI)
│           ├── login/                   # Interfaz de inicio de sesión
│           └── users/                   # Interfaz completa del CRUD de usuarios
│
└── README.md                            # Documentación principal del proyecto

---

🚀 Instalación y Puesta en Marcha

Prerrequisitos

• Crystal >= 1.20.0 y Lucky CLI
• Node.js >= 18.x y npm
• PostgreSQL >= 14.x (o Docker)

---

Paso 1: Clonar el repositorio

git clone https://github.com/tu-usuario/forgeworks.git
cd forgeworks

---

Paso 2: Configurar y Levantar el Backend (forgeworks_api)

1. Navegar a la carpeta del backend:

   cd forgeworks_api
   

2. Instalar dependencias de Crystal:

   shards install
   

3. Configurar variables de entorno (crear archivo .env si es necesario):

   # Configuración por defecto de PostgreSQL
   DB_HOST=localhost
   DB_PORT=5432
   DB_USERNAME=postgres
   DB_PASSWORD=postgres
   

4. Crear la base de datos y ejecutar las migraciones:

   lucky db.create
   lucky db.migrate
   

5. Iniciar el servidor API (por defecto en el puerto 3000):

   lucky dev
   # o alternativamente:
   crystal run src/forgeworks_api.cr
   

---

Paso 3: Configurar y Levantar el Frontend (forgeworks-web)

1. Abrir una nueva terminal y navegar a la carpeta web:

   cd forgeworks-web
   

2. Instalar paquetes de npm:

   npm install
   

3. Iniciar el servidor de desarrollo de Angular:

   ng serve
   

4. Abrir en el navegador:

   http://localhost:4200
   

---

🔑 Credenciales de Prueba

Para facilitar la evaluación de la entrega y las pruebas del sistema, puede utilizar los siguientes datos de acceso:

---