docs: update README

.github/workflows/find-impulsa-web.yml

@@ -1,17 +0,0 @@
-name: Find Impulsa Web
-
-on:
-  workflow_dispatch:
-
-jobs:
-  find:
-    runs-on: self-hosted
-    steps:
-      - name: Inspect impulsa_landing container
-        run: |
-          echo "=== Mounts ==="
-          docker inspect impulsa_landing --format '{{range .Mounts}}Source={{.Source}} Dest={{.Destination}}{{"\n"}}{{end}}'
-          echo "=== Traefik labels ==="
-          docker inspect impulsa_landing --format '{{range $k,$v := .Config.Labels}}{{$k}}={{$v}}{{"\n"}}{{end}}' | grep -i traefik
-          echo "=== index.html ==="
-          docker exec impulsa_landing cat /usr/share/nginx/html/index.html

README.md

@@ -1,98 +1,121 @@
-<p align="center">
-  <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
-</p>
+# api-ubigeo
 
-[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456
-[circleci-url]: https://circleci.com/gh/nestjs/nest
+NestJS REST API for Peruvian geographic codes (UBIGEO) and world countries. Provides departments, provinces, and districts sourced from INEI 2025, with full-text search and Redis cache.
 
-  <p align="center">A progressive <a href="http://nodejs.org" target="_blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
-    <p align="center">
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/dm/@nestjs/common.svg" alt="NPM Downloads" /></a>
-<a href="https://circleci.com/gh/nestjs/nest" target="_blank"><img src="https://img.shields.io/circleci/build/github/nestjs/nest/master" alt="CircleCI" /></a>
-<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
-<a href="https://opencollective.com/nest#backer" target="_blank"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
-<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
-  <a href="https://paypal.me/kamilmysliwiec" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg" alt="Donate us"/></a>
-    <a href="https://opencollective.com/nest#sponsor"  target="_blank"><img src="https://img.shields.io/badge/Support%20us-Open%20Collective-41B883.svg" alt="Support us"></a>
-  <a href="https://twitter.com/nestframework" target="_blank"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow" alt="Follow us on Twitter"></a>
-</p>
-  <!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
-  [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
+## Stack
 
-## Description
+- NestJS 11 + TypeScript 5.7
+- Prisma 7 + PostgreSQL 16 (driver adapter pg)
+- Redis (cache-manager + @keyv/redis)
+- Swagger / OpenAPI
+- Helmet + compression
+- Docker + Docker Compose
 
-[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
+## Features
 
-## Project setup
+- List and search all 25 Peruvian departments
+- List and search provinces (filter by department)
+- List and search districts (filter by province)
+- Universal UBIGEO lookup by code (2, 4, or 6 digits)
+- Full-text search across departments, provinces, and districts
+- World countries endpoint with ISO codes, region, coordinates
+- Filter countries by region
+- HTTP cache headers (24h `Cache-Control` on all read endpoints)
+- Swagger UI at `/api/docs`
+- Health check endpoint
+- Seeded database via `prisma/seed`
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 22
+- PostgreSQL 16
+- Redis (optional, for distributed cache)
+
+### Installation
 
 ```bash
-$ npm install
+npm install
 ```
 
-## Compile and run the project
+### Database Setup
 
 ```bash
-# development
-$ npm run start
+# Run migrations
+npm run prisma:migrate
 
-# watch mode
-$ npm run start:dev
+# Generate Prisma client
+npm run prisma:generate
 
-# production mode
-$ npm run start:prod
+# Seed the database
+npm run seed
 ```
 
-## Run tests
+### Running
 
 ```bash
-# unit tests
-$ npm run test
+# Development
+npm run start:dev
 
-# e2e tests
-$ npm run test:e2e
-
-# test coverage
-$ npm run test:cov
+# Production
+npm run start:prod
 ```
 
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `DATABASE_URL` | PostgreSQL connection string | Yes |
+| `PORT` | Server port | No (default: `3200`) |
+| `NODE_ENV` | Environment (`development` / `production`) | No |
+
+## API Endpoints
+
+All routes are prefixed with `/api/v1`.
+
+### UBIGEO
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/v1/ubigeo/stats` | General stats (counts per level) |
+| `GET` | `/api/v1/ubigeo/lookup/:codigo` | Universal lookup by code (2, 4, or 6 digits) |
+| `GET` | `/api/v1/ubigeo/departamentos` | List all departments (supports `?q=` search) |
+| `GET` | `/api/v1/ubigeo/departamentos/:codigo` | Get department with its provinces |
+| `GET` | `/api/v1/ubigeo/provincias` | List provinces (supports `?q=` search, `?dep=` filter) |
+| `GET` | `/api/v1/ubigeo/provincias/:codigo` | Get province with its districts |
+| `GET` | `/api/v1/ubigeo/distritos` | List districts (supports `?q=` search, `?prov=` filter) |
+| `GET` | `/api/v1/ubigeo/distritos/:codigo` | Get district by 6-digit code |
+
+### Countries
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/v1/paises/stats` | Country statistics |
+| `GET` | `/api/v1/paises/regiones` | List world regions |
+| `GET` | `/api/v1/paises` | List countries (supports `?q=` search, `?region=` filter) |
+| `GET` | `/api/v1/paises/:codigo` | Get country by ISO alpha-2 (PE) or alpha-3 (PER) |
+
+### Health
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/v1/health` | Health check |
+
 ## Deployment
 
-When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information.
-
-If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps:
+Docker Compose setup included for local development and production.
 
 ```bash
-$ npm install -g @nestjs/mau
-$ mau deploy
+# Local development
+docker-compose up -d
+
+# Production
+docker-compose -f docker-compose.production.yml up -d
 ```
 
-With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.
-
-## Resources
-
-Check out a few resources that may come in handy when working with NestJS:
-
-- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework.
-- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy).
-- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/).
-- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks.
-- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com).
-- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com).
-- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs).
-- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com).
-
-## Support
-
-Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
-
-## Stay in touch
-
-- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
-- Website - [https://nestjs.com](https://nestjs.com/)
-- Twitter - [@nestframework](https://twitter.com/nestframework)
+Swagger documentation: `http://localhost:3200/api/docs`
 
 ## License
 
-Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).
+Private

docs/active_context.md

@@ -1,58 +0,0 @@
-# Active Context - api-ubigeo
-
-> Última actualización: 2026-03-10
-
-## Estado Actual
-
-**PRODUCCIÓN ACTIVA** — `https://api-ubigeo.darkcodex.dev` responde correctamente desde internet.
-
-- Health: `GET /api/v1/health` → `{"status":"ok"}`
-- Distritos: `GET /api/v1/ubigeo/distritos?q=lima&limit=10` → HTTP 200
-
-## Decisiones Recientes
-
-### 2026-03-10
-- **Traefik en Easypanel usa file provider con `main.yaml`** — NO es `directory:`, solo lee ese único archivo
-- El archivo `api-ubigeo.yaml` separado que creamos antes era ignorado por Traefik
-- **Solución**: inyectar los routers/services directamente en `main.yaml` usando `jq` vía `docker run -v`
-- El runner de Gitea corre en un contenedor sin acceso directo al host filesystem, pero puede usar `docker run -v /host/path:/container/path` para acceder a rutas del host
-- `main.yaml` está en JSON (no YAML real), Traefik lo acepta igual
-- Routers agregados: `http-ubigeo-0` (redirect https) y `https-ubigeo-0` (TLS letsencrypt)
-- Service: `ubigeo_api-0` → `http://ubigeo-api:3200/`
-
-## Infraestructura
-
-### Contenedor
-- Imagen: `ubigeo-api:latest` (multi-stage build, node:20-alpine)
-- Puerto interno: 3200
-- Redes: `api-ubigeo_ubigeo_network` + `easypanel`
-- Deploy path: `/home/deployer/api-ubigeo/`
-
-### Traefik
-- Config file: `/etc/easypanel/traefik/config/main.yaml` (JSON)
-- El CI inyecta routers via `jq` con `docker run -v`
-- Idempotente: verifica si `https-ubigeo-0` ya existe antes de agregar
-
-### CI/CD
-- Gitea runner: `contabo-runner` en `gitea_gitea_net`
-- Runner corre en contenedor pero con acceso a Docker socket del host
-- Workflow: `.github/workflows/deploy.yml`
-- Run exitoso: #29
-
-## Pendiente Próxima Sesión
-
-- Nada crítico en api-ubigeo
-- Pendiente en Impulsa Mobile: probar autocomplete de distrito con API live
-
-## Contexto Técnico
-
-### Workarounds
-- `main.yaml` se sobreescribe en cada deploy de Easypanel → el CI debe reinjectar la ruta si eso ocurre
-- El step `Register Traefik route` es idempotente (no duplica si ya existe)
-
-### Archivos Clave
-- `.github/workflows/deploy.yml` — CI/CD completo
-- `docker-compose.production.yml` — producción con red easypanel
-- `scripts/register-traefik.sh` — script legacy (ya no se usa, se puede eliminar)
-- `src/modules/ubigeo/ubigeo.controller.ts` — endpoints
-- `src/modules/ubigeo/dto/ubigeo.dto.ts` — DTOs