Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/BladimirGS/judicial-backend/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through setting up a local development instance of Judicial Backend from scratch. By the end you will have the Express server running, connected to a SQL Server database, and you will have exchanged credentials for a JWT access token that you can use against any protected endpoint.
1

Install prerequisites

Before you clone the repository, make sure the following are available in your environment:
DependencyMinimum versionCheck
Node.js18.xnode --version
npm9.x (bundled with Node 18)npm --version
SQL Server2017+ (or Azure SQL)connection string must be reachable
The SQL Server instance must already exist and have the target database created. Judicial Backend uses TypeORM in non-synchronize mode — it will not create or alter tables at startup. Apply your schema migrations before starting the server.
For local development on macOS or Linux you can run SQL Server in Docker:
docker run -e "ACCEPT_EULA=Y" -e "SA_PASSWORD=YourStrong!Passw0rd" \
  -p 1433:1433 --name sqlserver \
  mcr.microsoft.com/mssql/server:2022-latest
2

Clone the repository and install dependencies

# Clone the repository
git clone <url-del-repo> judicial-backend
cd judicial-backend

# Install all dependencies (production + dev)
npm install
After installation the key runtime packages will be present: Express 5, TypeORM, mssql, pdfmake, ExcelJS, Pino, and the JWT/JWKS libraries. Dev tooling includes nodemon, ts-node, Jest, ESLint, and Prettier.
3

Configure environment variables

Copy the example environment file and open it in your editor:
cp .env.example .env
At minimum you must supply values for the seven variables marked as required — the application calls process.exit(1) at boot if any of them is empty:
# Required: database connection
DB_HOST=localhost
DB_USER=sa
DB_PASSWORD=YourStrong!Passw0rd
DB_NAME=judicial_db

# Required: external authentication (BFF)
EXTERNAL_AUTH_URL=https://auth.yourdomain.internal
JWT_ISSUER=https://auth.yourdomain.internal
JWT_AUDIENCE=judicial-backend

# Recommended: system identifier sent to the auth service
ID_SISTEMA=1
The remaining variables have safe defaults (PORT=4000, DB_PORT=1433, NODE_ENV=development, etc.) — you only need to override them when deploying to staging or production. See the Configuration reference for every available variable.
EXTERNAL_AUTH_URL must point to a running instance of the identity provider that exposes POST /api/Auth/Login, POST /api/Auth/RefreshToken, and GET /api/AuthJWT/GetJwks. Without it the protect middleware cannot fetch the JWKS public keys needed to verify incoming JWTs.
4

Start the development server

npm run dev
nodemon watches src/ for TypeScript changes and restarts automatically. On a successful start you will see Pino log output similar to:
{"level":30,"msg":"Corriendo en http://localhost:4000"}
Two URLs are immediately available:
URLDescription
http://localhost:4000/apiREST API root — all module routes live under /api
http://localhost:4000/api-docsInteractive Swagger UI with all documented endpoints
http://localhost:4000/api-docs.jsonRaw OpenAPI 3.0 JSON spec
To run the compiled production build instead, execute npm run build followed by npm start. The compiled output lands in dist/.
5

Make your first authenticated API call

All protected routes require a valid Bearer JWT in the Authorization header. Start by obtaining a token from the login endpoint.Step 5a — Log in and receive an access token:
curl -X POST http://localhost:4000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"usuario": "your-user", "contrasenia": "your-password"}'
A successful response returns a JSON body with an access_token field and sets a Secure; HttpOnly refresh-token cookie:
{
  "status": "success",
  "message": "Inicio de sesión exitoso",
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
Step 5b — Call a protected route using the access token:Copy the access_token value and pass it as a Bearer token. The following request fetches the appeal catalogues for the criminal (penal) matter type:
curl http://localhost:4000/api/apelaciones/catalogos?materia=penal \
  -H 'Authorization: Bearer <access_token>'
You should receive a 200 OK response with catalogue data (courts, rooms, magistrates, etc.) populated from your SQL Server database.
All routes under /api/apelaciones, /api/busquedas, and /api/estadisticas require a valid Bearer JWT. Only the /api/auth/* endpoints (login, refresh, logout) are publicly accessible without a token.

​
Available npm scripts

ScriptDescription
npm run devStart dev server with nodemon (ts-node, hot reload)
npm run buildCompile TypeScript to dist/
npm startRun compiled output from dist/server.js
npm testRun Jest test suite
npm run test:watchRun Jest in interactive watch mode
npm run test:coverageRun tests with coverage report
npm run lintRun ESLint on src/**/*.ts
npm run lint:fixAuto-fix ESLint violations
npm run format:checkCheck formatting with Prettier (no writes)
npm run format:fixAuto-format with Prettier
npm run fix:allRun Prettier then ESLint fix in sequence

Build docs developers (and LLMs) love

Get started for freeTalk to us