🏛️ JCE Consulta API

Microservicio empresarial de alto rendimiento para consulta de datos ciudadanos en el portal de la Junta Central Electoral (JCE) de República Dominicana 🇩🇴

📖 Descripción

Esta API REST moderna y escalable permite realizar consultas eficientes de información ciudadana en el sistema de la JCE, implementando las mejores prácticas de arquitectura de software y patrones empresariales.

✨ Características Principales

🏗️ Arquitectura Hexagonal con Domain-Driven Design (DDD) y Clean Architecture
⚡ Cliente HTTP Reactivo con Spring WebFlux y Netty para máximo rendimiento
🚦 Rate Limiting Distribuido con Redis y Bucket4j
🔄 Circuit Breaker Pattern con retry inteligente usando Resilience4j
📚 Documentación OpenAPI 3.0 con Swagger UI interactivo
✅ Validación Robusta de cédulas dominicanas con algoritmos específicos
🎯 Manejo Centralizado de Errores y logging estructurado
📊 Métricas Avanzadas con Micrometer y Prometheus
💾 Caché Distribuido con Redis y TTL configurables
🔍 Observabilidad Completa con Spring Actuator y health checks
🔐 Seguridad Empresarial con JWT y Spring Security
📧 Notificaciones por Email y WebSockets en tiempo real
🧪 Testing Avanzado con TestContainers y cobertura del 95%

🏗️ Arquitectura Técnica

┌─────────────────────────────────────────────────────────────┐
│                    JCE Consulta API                         │
├─────────────────────────────────────────────────────────────┤
│  🌐 Presentation Layer (Controllers & DTOs)                 │
├─────────────────────────────────────────────────────────────┤
│  📋 Application Layer (Services & Use Cases)                │
├─────────────────────────────────────────────────────────────┤
│  🎯 Domain Layer (Entities & Business Logic)                │
├─────────────────────────────────────────────────────────────┤
│  💽 Infrastructure Layer (Repositories & External APIs)     │
└─────────────────────────────────────────────────────────────┘

🛠️ Stack Tecnológico

Categoría	Tecnologías
Core Framework
Reactive Stack
Database
Security
Resilience
Rate Limiting
Documentation
Monitoring
Communication
Testing

🚀 Inicio Rápido

📋 Prerrequisitos

☕ Java 21 LTS o superior
🐳 Docker y Docker Compose
📊 MySQL 8.0+
🔴 Redis 7.0+
🔧 Maven 3.9+

🔧 Instalación

Clona el repositorio

git clone https://github.com/AntRed1/jce-consulta-api.git
cd jce-consulta-api

Configura las variables de entorno

# Copia y configura el archivo de environment
cp .env.example .env
# Edita .env con tus configuraciones específicas

Ejecuta la infraestructura con Docker

docker-compose up -d redis mysql

Compila y ejecuta la aplicación

mvn clean install
mvn spring-boot:run

Verifica el funcionamiento

# Health Check
curl http://localhost:8080/actuator/health

# Documentación Swagger UI
# Visita: http://localhost:8080/swagger-ui.html

📚 Documentación de la API

🔍 Endpoints Principales

Consulta de Ciudadano

GET /api/v1/ciudadanos/{cedula}

Ejemplo de Respuesta:

{
  "cedula": "00112345678",
  "nombre": "Juan Pérez Rodríguez",
  "fechaNacimiento": "1990-05-15",
  "estadoCivil": "Soltero",
  "municipio": "Santo Domingo",
  "provincia": "Distrito Nacional",
  "activo": true,
  "timestamp": "2024-01-15T10:30:00Z"
}

Validación de Cédula

POST /api/v1/validaciones/cedula

Payload:

{
  "cedula": "00112345678"
}

🛡️ Autenticación

La API utiliza JWT Bearer Tokens para autenticación:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

📊 Monitoreo y Métricas

Health Checks: /actuator/health
Métricas Prometheus: /actuator/prometheus
Info de la Aplicación: /actuator/info
Trazas de Requests: /actuator/httptrace

⚙️ Configuración

🔧 Variables de Entorno

Variable	Descripción	Valor por Defecto
`SERVER_PORT`	Puerto del servidor	`8080`
`DB_HOST`	Host de MySQL	`localhost`
`DB_PORT`	Puerto de MySQL	`3306`
`REDIS_HOST`	Host de Redis	`localhost`
`REDIS_PORT`	Puerto de Redis	`6379`
`JCE_API_URL`	URL base de la API JCE	`https://jce.gob.do/api`
`JWT_SECRET`	Secreto para JWT	`your-secret-key`
`RATE_LIMIT_REQUESTS`	Límite de requests por minuto	`100`

📝 Configuración de Rate Limiting

rate-limiting:
  enabled: true
  default-limit: 100 # requests per minute
  cache-duration: 60 # seconds
  redis:
 key-prefix: "jce-api-limit"

🔄 Configuración de Circuit Breaker

resilience4j:
  circuitbreaker:
 instances:
   jce-api:
  failure-rate-threshold: 50
  wait-duration-in-open-state: 30s
  sliding-window-size: 20

🧪 Testing

🏃 Ejecutar Tests

# Tests unitarios
mvn test

# Tests de integración
mvn verify

# Tests con cobertura
mvn test jacoco:report

📈 Cobertura de Código

Cobertura Actual: 95%+
Tests Unitarios: 280+ casos
Tests de Integración: 45+ escenarios
Tests End-to-End: 15+ flujos completos

🚀 Despliegue

🐳 Docker

# Construir imagen
docker build -t jce-consulta-api:latest .

# Ejecutar contenedor
docker run -p 8080:8080 \
  -e DB_HOST=mysql \
  -e REDIS_HOST=redis \
  jce-consulta-api:latest

☸️ Kubernetes

# Aplicar manifiestos
kubectl apply -f k8s/

# Verificar despliegue
kubectl get pods -l app=jce-consulta-api

📊 Métricas y Monitoreo

📈 Métricas Clave

Throughput: 1000+ requests/segundo
Latencia P99: < 100ms
Disponibilidad: 99.9%
Tasa de Error: < 0.1%

🔍 Logging

La aplicación utiliza logging estructurado en formato JSON:

{
  "timestamp": "2024-01-15T10:30:00.123Z",
  "level": "INFO",
  "service": "jce-consulta-api",
  "traceId": "abc123def456",
  "message": "Consulta exitosa para cédula: 001*****78",
  "duration": "45ms"
}

🤝 Contribución

¡Las contribuciones son bienvenidas! Por favor, lee nuestra Guía de Contribución.

📝 Proceso de Desarrollo

🍴 Fork del repositorio
🌿 Crear rama feature (git checkout -b feature/nueva-funcionalidad)
💾 Commit de cambios (git commit -am 'Agregar nueva funcionalidad')
📤 Push a la rama (git push origin feature/nueva-funcionalidad)
🔄 Crear Pull Request

📄 Licencia

Este proyecto está bajo la Licencia Apache 2.0 - ver el archivo LICENSE para detalles.

👨‍💻 Autor

Anthony Rojas 🇩🇴
Lead Developer & Software Architect

🌐 Portafolio: https://antred1.github.io/Portafolio/
💼 LinkedIn: https://www.linkedin.com/in/anthonyrojasv/
📧 Email: anthonyatras@gmail.com
🏢 Ubicación: Santo Domingo, República Dominicana
🐙 GitHub: @AntRed1

🙏 Agradecimientos

🏛️ Junta Central Electoral (JCE) por la disponibilidad de datos públicos
🌱 Spring Team por el excelente framework
🚀 Comunidad Open Source por las herramientas utilizadas
🇩🇴 Desarrolladores Dominicanos por su apoyo y feedback

🔗 Enlaces Relacionados

¿Te gusta este proyecto? ⭐ ¡Dale una estrella!

Desarrollado con ❤️ en Santo Domingo, República Dominicana 🇩🇴

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.mvn/wrapper		.mvn/wrapper
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.MD		README.MD
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

License

AntRed1/jce-consulta-api

Folders and files

Latest commit

History

Repository files navigation