Module Reference: apelacion, busqueda, estadistica, auth

Judicial Backend partitions all business logic into four self-contained domain modules. Each module lives under src/modules/<name>/ and owns its routes, controllers, services, repositories, mappers, and types. No module imports directly from another; shared infrastructure is accessed through database/, shared/, and core/ only.

Module: `apelacion`

The apelacion module is the primary intake interface for the court’s second-instance proceedings. It handles the capture and registration of new appeals (apelaciones) submitted to the Oficialía, including their attachments (anexos), folio generation, and Sala/Toca assignment via stored procedures.

Routes

All routes are mounted at /api/apelaciones and require a valid JWT (enforced in routes/index.ts).

Method	Path	Handler	Description
`GET`	`/catalogos`	`ApelacionController.getCatalogos`	Load drop-down catalogs for the appeal intake form
`GET`	`/:idMunicipio/localidades`	`ApelacionController.getLocalidades`	Localidades filtered by municipality
`GET`	`/:idApelacion/tipos-apelacion`	`ApelacionController.getTiposApelacion`	Appeal sub-types filtered by appeal category
`GET`	`/detalle`	`ApelacionController.getByFolio`	Retrieve a full appeal record by folio number
`POST`	`/`	`ApelacionController.create`	Register a new appeal (validated against `CreateApelacionDTO`)
`POST`	`/anexos`	`AnexoController.create`	Attach documents to an existing appeal
`GET`	`/anexos/catalogos`	`AnexoController.getCatalogos`	Load catalog of attachment types

Appeal Payload Types

The POST / endpoint accepts one of two union payload shapes depending on whether the appeal involves indigenous defendants:

// src/modules/apelacion/types/apelacion-payload.type.ts
type ApelacionPayload = ApelacionPenalPayload | ApelacionIndigenaPayload;

ApelacionPenalPayload — Standard criminal appeal; includes defendants, offenses, and sentencing data.
ApelacionIndigenaPayload — Extends the penal payload with ethnicity and language fields required for indigenous cases.

Service Factory Pattern

Services in this module use functional factory constructors, receiving all repository dependencies as arguments:

export const createApelacionService = (
    catalogoRepo,       // CatalogoOrmRepository — catalog lookups
    asignacionRepo,     // AsignacionTocaSalaSpRepository — Sala/Toca assignment SP
    folioRepo,          // FolioSpRepository — folio generation SPs
    apelacionRepo,      // ApelacionRepository — ORM CRUD on Apelacion entity
    getManagerFn = getManager, // optional; defaults to the live DataSource manager
) => ({
    getCatalogos: (materia: string) => { /* … */ },
    getLocalidades: (idMunicipio: number) => { /* … */ },
    getTiposApelacion: (idApelacion: number) => { /* … */ },
    getByFolio: (folioOficialia: string) => { /* … */ },
    create: (data: CreateApelacionDTO) => { /* … */ },
});

Because every dependency is injected at construction time, test suites can supply mock repositories to createApelacionService without any patching framework. Replacing folioRepo with a stub that returns a fixed folio string is sufficient to unit-test the full registration flow in isolation.

Apelación — layer breakdown

Layer	File	Responsibility
Interface	`controllers/apelacion.controller.ts`	Validates query params, calls service, returns response via `responseUtil`
Interface	`controllers/anexo.controller.ts`	Attachment endpoints
Interface	`apelacion.routes.ts`	Registers routes; applies `validateDto` middleware
Application	`services/apelacion.service.ts`	Orchestrates ORM repos + SPs inside a single transaction
Application	`services/anexo.service.ts`	Business logic for attachment management
Transformation	`mappers/apelacion.mapper.ts`	`Apelacion` entity → `ApelacionDetailDTO`
Transformation	`mappers/anexo.mapper.ts`	`ApelacionAnexo` entity → `AnexoDTO`
Infrastructure	`repositories/apelacion.repository.ts`	`createApelacion()`, `findOneByFolio()` via TypeORM
Infrastructure	`repositories/anexo.repository.ts`	`addAnexos()`, list annexes
Infrastructure	`database/repositories/folio.sp-repository.ts`	Stored procs: `PA_SEL_FolioNomenclaturaToca`, `PA_INS_PCF_FolioTramite`
Infrastructure	`database/repositories/asignacion-toca-sala.sp-repository.ts`	Stored proc: `PA_SEL_AsignacionTocaySala`
Domain	`types/apelacion-payload.type.ts`	`ApelacionPenalPayload \| ApelacionIndigenaPayload`
Domain	`types/anexo-payload.type.ts`	`AnexoItemPayload`, `AddAnexosPayload`

Module: `busqueda`

The busqueda module provides a parameterized search interface over existing appeals, with results exportable as Excel (.xlsx) or PDF. It offers three independent search sub-modes, each with its own controller, service, repository, mapper, and report builders.

Routes

All routes are mounted at /api/busquedas and require a valid JWT.

Method	Path	Description
`GET`	`/filtros`	Catalogs for the full-appeal search form
`GET`	`/`	Search full appeals (with Partes and Anexos)
`GET`	`/exportar-excel`	Export full-appeal results as `.xlsx`
`GET`	`/exportar-pdf`	Export full-appeal results as PDF
`GET`	`/plano`	Search flat appeals (no Partes/Anexos)
`GET`	`/plano/exportar-excel`	Export flat results as `.xlsx`
`GET`	`/plano/exportar-pdf`	Export flat results as PDF
`GET`	`/historico/filtros`	Catalogs for the historical search form
`GET`	`/historico`	Search historical appeal entities
`GET`	`/historico/exportar-excel`	Export historical results as `.xlsx`
`GET`	`/historico/exportar-pdf`	Export historical results as PDF

Three Search Sub-Modes

Sub-mode	Entity queried	Includes	Use case
Completa	`Apelacion`	All relations — Partes, Anexos, Catálogos	Full case review
Plana	`Apelacion`	Basic scalar fields and catalog IDs only	Tabular exports, reporting
Histórica	`ApelacionHistorico`	Simple catalog relations	Historical audit trails

Standard Service Contract

Every service in this module exposes the same four methods:

Method	Signature	Description
`obtenerCatalogos()`	`(): Promise<CatalogosDTO>`	Returns drop-down data for the filter form
`buscar(filtros)`	`(filtros: FiltrosDTO): Promise<ResultadoDTO[]>`	Paginated and filtered query
`exportarExcel(filtros)`	`(filtros: FiltrosDTO): Promise<Buffer>`	Builds an `.xlsx` workbook buffer from search results
`exportarPdf(filtros)`	`(filtros: FiltrosDTO): Promise<Buffer>`	Builds a PDF buffer from search results

Export endpoints stream the buffer directly to the HTTP response using responseUtil.file(), which sets Content-Disposition: attachment and the appropriate MIME type (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for Excel, application/pdf for PDF).

Búsqueda — layer breakdown

Layer	File	Responsibility
Interface	`controllers/busqueda-apelacion.controller.ts`	`getCatalogos`, `getApelaciones`, `exportarExcel`, `exportarPdf`
Interface	`controllers/busqueda-plano.controller.ts`	Same surface for the flat projection
Interface	`controllers/busqueda-historico.controller.ts`	Same surface for the historical projection
Application	`services/busqueda-apelacion.service.ts`	Calls repository, applies mapper, dispatches to report builder
Application	`services/busqueda-plano.service.ts`	Flat query variant
Application	`services/busqueda-historico.service.ts`	Historical query variant
Transformation	`mappers/apelacion.mapper.ts`	`Apelacion` → `ApelacionDTO` (full)
Transformation	`mappers/apelacion-plano.mapper.ts`	`Apelacion` → `ApelacionPlanoDTO`
Transformation	`mappers/apelacion-historica.mapper.ts`	`ApelacionHistorico` → `ApelacionHistoricoDTO`
Infrastructure	`repositories/busqueda-apelacion.repository.ts`	Deep `QueryBuilder` with Partes + Anexos JOINs
Infrastructure	`repositories/busqueda-plano.repository.ts`	Shallow `QueryBuilder` — no Partes/Anexos
Infrastructure	`repositories/busqueda-historico.repository.ts`	`QueryBuilder` over `ApelacionHistorico`
Reports	`reports/excel/*.report.ts`	Build Excel buffers via `shared/excel`
Reports	`reports/pdf/*.report.ts`	Build PDF buffers via `shared/pdf`

Module: `estadistica`

The estadistica module generates statistical reports on court appeals. All data is retrieved through a single stored procedure (PA_SEL_PCF_EstadisticaApelaciones) and then shaped by mappers into one of two presentation modes before being returned as JSON or exported to Excel.

Routes

All routes are mounted at /api/estadisticas and require a valid JWT.

Method	Path	Handler	Description
`GET`	`/plano`	`EstadisticaController.getReportePlano`	Flat list of statistical records
`GET`	`/agrupado`	`EstadisticaController.getReporteAgrupado`	Records grouped by Sala and appeal type
`POST`	`/exportar`	`EstadisticaController.exportarExcel`	Export statistics to Excel (three format options)

Two Report Modes

Mode	Mapper	Result shape
Plano	`estadistica.mapper.ts`	One row per appeal — raw SP result mapped to a flat DTO
Agrupado	`estadistica-agrupado.mapper.ts`	SP results grouped by Sala/Apelación; suitable for pivot tables and charts

Excel Export Formats

The POST /exportar endpoint supports three Excel output formats within the same workbook, generated by dedicated report builders in reports/excel/:

Report file	Sheet content
`estadistica-plano-excel.report.ts`	Flat tabular list
`estadistica-agrupado-excel.report.ts`	Grouped summary with subtotals
`estadistica-grafico-excel.report.ts`	Chart-ready data layout

Estadística — layer breakdown

Layer	File	Responsibility
Interface	`controllers/estadistica.controller.ts`	Endpoints `/plano`, `/agrupado`, `/exportar`
Interface	`estadistica.routes.ts`	Route registration
Application	`services/estadistica.service.ts`	Calls SP repository, selects mapper, builds Excel report
Transformation	`mappers/estadistica.mapper.ts`	SP result row → flat DTO
Transformation	`mappers/estadistica-agrupado.mapper.ts`	Groups SP rows by Sala/Apelación
Infrastructure	`database/repositories/estadistica.sp-repository.ts`	Executes `PA_SEL_PCF_EstadisticaApelaciones`
Reports	`reports/excel/estadistica-plano-excel.report.ts`	Flat Excel sheet
Reports	`reports/excel/estadistica-agrupado-excel.report.ts`	Grouped Excel sheet
Reports	`reports/excel/estadistica-grafico-excel.report.ts`	Chart-data Excel sheet

Module: `auth`

The auth module implements authentication using a Backend-for-Frontend (BFF) proxy pattern. The backend does not manage users or issue tokens itself; instead, it proxies credential exchanges to an external authentication API and validates the resulting JWTs locally using RS256 public keys fetched via JWKS.

Routes

Auth routes are mounted at /api/auth and are public — no protect middleware is applied at this level.

Method	Path	Handler	Description
`POST`	`/login`	`AuthController.login`	Authenticate with `{ usuario, contrasenia }`; sets `httpOnly` refresh-token cookie
`POST`	`/refresh`	`AuthController.refresh`	Exchange refresh token (from cookie) for a new access token
`POST`	`/logout`	`AuthController.logout`	Revoke the session on the external auth API and clear the cookie

JWT Protection for Business Modules

The protect middleware (modules/auth/middlewares/protect.middleware.ts) guards every non-auth route. It runs the following sequence on every incoming request:

Client → GET /api/apelaciones  (Authorization: Bearer <token>)
          │
          ▼
  protect middleware
    1. Extract Bearer token from Authorization header
    2. Decode JWT header → read key ID (kid)
    3. Fetch JWKS from external provider: GET .../GetJwks
    4. Verify RS256 signature, issuer, and audience
    5. Attach decoded payload to req.user
    6. Call next()
          │
          ▼
  ApelacionController / BusquedaController / EstadisticaController

BFF Proxy Flow

Client → POST /api/auth/login { usuario, contrasenia }
          │
          ▼
  AuthController.login()
          │
          ▼
  AuthExternalAdapter.login()  ──HTTP──► External Auth API
          │                                    │
          │◄───────────────────────────────────┤ { access_token, refreshToken }
          │
  Sets httpOnly cookie: refreshToken
  Responds: { access_token }

Required Environment Variables

Variable	Description
`EXTERNAL_AUTH_URL`	Base URL of the external authentication API
`JWT_ISSUER`	Expected `iss` claim in incoming JWTs
`JWT_AUDIENCE`	Expected `aud` claim in incoming JWTs
`ID_SISTEMA`	System identifier sent with login requests (`idSistema`)

All four variables are validated at startup. If any are missing, the application calls process.exit(1) before binding to the network port.

Auth — layer breakdown

Layer	File	Responsibility
Interface	`auth.routes.ts`	Registers `/login`, `/refresh`, `/logout`; applies `validateDto(LoginDto)` on login
Interface	`controllers/auth.controller.ts`	Extracts credentials, calls adapter, sets `httpOnly` cookie, returns `access_token`
Application	`middlewares/protect.middleware.ts`	Verifies RS256 Bearer JWT via JWKS; sets `req.user`; rejects with `401` on failure
Infrastructure	`adapters/auth-external.adapter.ts`	HTTP proxy client: `login()`, `refreshToken()`, `revoke()`
Domain	`types/auth.types.ts`	`JwtPayload` interface + global Express `Request.user` augmentation
Domain	`dtos/login.dto.ts`	`{ usuario: string, contrasenia: string }` with `class-validator` decorators

Get Started

Architecture

Authentication

Core Concepts

Report Generation

Module Reference: apelacion, busqueda, estadistica, auth

Module: `apelacion`

Routes

Appeal Payload Types

Service Factory Pattern

Module: `busqueda`

Routes

Three Search Sub-Modes

Standard Service Contract

Module: `estadistica`

Routes

Two Report Modes

Excel Export Formats

Module: `auth`

Routes

JWT Protection for Business Modules

BFF Proxy Flow

Required Environment Variables

Build docs developers (and LLMs) love

Get Started

Architecture

Authentication

Core Concepts

Report Generation

Documentation Index

​Module: apelacion

​Routes

​Appeal Payload Types

​Service Factory Pattern

​Module: busqueda

​Routes

​Three Search Sub-Modes

​Standard Service Contract

​Module: estadistica

​Routes

​Two Report Modes

​Excel Export Formats

​Module: auth

​Routes

​JWT Protection for Business Modules

​BFF Proxy Flow

​Required Environment Variables

Build docs developers (and LLMs) love

Module: `apelacion`

Routes

Appeal Payload Types

Service Factory Pattern

Module: `busqueda`

Routes

Three Search Sub-Modes

Standard Service Contract

Module: `estadistica`

Routes

Two Report Modes

Excel Export Formats

Module: `auth`

Routes

JWT Protection for Business Modules

BFF Proxy Flow

Required Environment Variables