Gradus

Plataforma de homologación académica (reconocimiento de créditos entre programas/instituciones) para el Politécnico Internacional, integrada con Universitas XXI (UXXI).

Arquitectura

Monorepo con cuatro servicios independientes:

gradus/
├── apps/
│   ├── identity/         # Proveedor OIDC de desarrollo (Next.js) — reemplaza Azure AD
│   ├── universitas/      # Portal académico + simulador UXXI (Next.js + Prisma + PostgreSQL)
│   ├── gradus/            # Frontend web — estudiante y coordinador (Next.js)
│   └── gradus-api/        # API REST — núcleo de homologación (ASP.NET Core 10, Clean Architecture)
├── docs/                  # Documentación del proyecto (índice en docs/README.md)
├── docker-compose.yml     # Infraestructura local (PostgreSQL + Redis)
└── init-databases.sh      # Inicialización de bases de datos

Servicios

identity — Proveedor de identidad

apps/identity/ · Puerto 3005

Servidor de autorización OpenID Connect mínimo que reemplaza a Azure AD en desarrollo. Emite los id_token/access_token (RS256, JWKS) que consumen gradus, universitas y gradus-api, de forma que apuntar las apps a él sea sólo configuración. Ver apps/identity/README.md.

Stack: Next.js 16 · TypeScript · Prisma · PostgreSQL · jose (JWT/JWKS)

Funcionalidades: login con sesión SSO, /authorize + /token (authorization_code + PKCE S256, refresh con rotación), descubrimiento OIDC + JWKS, dashboard de administración de usuarios/roles.

---

Universitas — Portal Académico

apps/universitas/ · Puerto 3003

Portal para estudiantes y coordinadores. Gestiona instituciones, facultades, programas, pensums, materias e historial académico. Expone además el simulador de la API UXXI que usa gradus-api en modo Uxxi:Mode=simulator.

Stack: Next.js 16 · TypeScript · Prisma · PostgreSQL · Tailwind CSS v4 · shadcn/ui

Funcionalidades:

• Login OIDC (Authorization Code + PKCE) contra identity, con fallback a Azure AD si no hay OIDC_ISSUER
• Portal del estudiante: historial académico, progreso por semestre
• Portal del coordinador: gestión académica
• Simulador de la API de UXXI (/ac_apipr/uxxiac_apipr/...) para pruebas del ACL de Gradus.API

Modelos principales: Institution → Faculty → Program → Pensum → Subject · Student · AcademicRecord · PartialGrade

---

Gradus Web — Frontend

apps/gradus/ · Puerto 3004

Frontend principal de la plataforma de homologación.

Stack: Next.js 16 · TypeScript · Tailwind CSS v4 · shadcn/ui · SignalR Client

Funcionalidades:

• Login OIDC (Authorization Code + PKCE) contra identity, con fallback a Azure AD, y redirección basada en roles.
• Conexión en tiempo real para notificaciones (SignalR).

---

Gradus.API — Backend

apps/gradus-api/ · Puerto 5002

API REST con Clean Architecture en 4 capas. Soporta el core de la plataforma de homologación.

Stack: .NET 10 · ASP.NET Core · C# · Entity Framework Core · MediatR · SignalR · QuestPDF

Funcionalidades:

• Autenticación y autorización JWT Bearer, validada contra el descubrimiento OIDC de identity (o Azure AD en producción real) — AzureAd:Authority en configuración.
• Arquitectura CQRS con MediatR.
• Generación de documentos en formato PDF con QuestPDF.
• WebSockets para notificaciones en tiempo real (SignalR).
• Rate limiting en endpoints de mutación, partitioned por usuario.

Proyectos:

Capa	Proyecto
Web / HTTP	Gradus.API
Lógica de negocio	Gradus.Application
Entidades de dominio	Gradus.Domain
Datos / externos	Gradus.Infrastructure

---

Infraestructura

Levantada con Docker Compose:

Servicio	Imagen	Puerto	Base de datos
PostgreSQL	postgres:18-alpine	5432	identity_db, universitas_db, gradus_db
Redis	redis:8.4-alpine	6379	—

Inicio rápido

Guía completa, paso a paso, con todas las variables de entorno: docs/SETUP.md.

Resumen del orden de arranque (cada app en su propia terminal):

# 1. Infraestructura (crear .env en la raíz, no hay .env.example — ver docs/SETUP.md §4.1)
echo "POSTGRES_DB_PASSWORD=secret" > .env && docker compose up -d

# 2. identity — debe estar arriba antes que los demás (autentica a todos)
cd apps/identity && cp .env.example .env && pnpm install \
  && pnpm run keys:generate && pnpm run db:migrate && pnpm run db:seed && pnpm run dev

# 3. gradus-api (crear antes appsettings.Development.json — ver docs/SETUP.md §6.2)
cd apps/gradus-api && dotnet restore && dotnet run --project Gradus.API

# 4. universitas
cd apps/universitas && cp .env.example .env.local && pnpm install \
  && npx prisma migrate deploy && npx prisma db seed && pnpm run dev

# 5. gradus
cd apps/gradus && cp .env.example .env.local && pnpm install && pnpm run dev

Despliegue

Guía paso a paso para desplegar en Railway (entorno de verificación/dev, sin Azure AD, con el simulador UXXI): docs/despliegue-dev.md.

Manual de uso y pruebas del entorno de dev ya desplegado, en lenguaje no técnico (para PM/QA): docs/MANUAL-PRUEBAS-DEV.md.

Variables de entorno

Ver la sección Apéndice de docs/SETUP.md para el listado completo por app. Todas las variables sensibles viven en archivos .env/.env.local (gitignored) o en dotnet user-secrets para gradus-api — nunca en appsettings.json.

Documentación

Índice completo en docs/README.md. Organización por carpetas:

Carpeta / archivo	Contenido
docs/SETUP.md	Instalación y puesta en marcha local, paso a paso
docs/despliegue-dev.md	Despliegue en Railway (entorno de verificación)
docs/MANUAL-PRUEBAS-DEV.md	Manual de uso y pruebas en lenguaje no técnico (PM/QA)
docs/fundacion/	Brief, plan técnico, tasks y esquemas de BD
docs/integracion-uxxi/	⭐ Trabajo activo: análisis, plan de implementación, diseño del ACL y specs de UXXI (specs/)
docs/features/	Planes de funcionalidades y reportes de bugs
docs/guias/	Guías de setup y de trabajo con Claude
docs/auditoria/	Auditoría técnica externa

Tecnologías

Categoría	Tecnología
Frontend	Next.js 16, TypeScript, Tailwind CSS v4, shadcn/ui
Backend	ASP.NET Core 10, C#, MediatR (CQRS)
ORM	Prisma (identity, Universitas), Entity Framework Core (Gradus.API)
Base de datos	PostgreSQL 18
Caché	Redis 8.4
Autenticación	OIDC — identity (desarrollo) o Azure AD / Entra ID, JWT (RS256)
Contenedores	Docker Compose
Tiempo Real	SignalR (WebSockets)
Documentos	QuestPDF