convez.ai
AgenteDevOps & InfraestruturaAvançado
matiaspakua

Notaire – Modernização de Sistema de Gestão para Cartórios

matiaspakua/notaire

Migração de monolito Java legado para microserviços modernos com automação completa

Ver no GitHub
InicialPluginScore · de 0 a 100

Plataforma completa de migração de um monolito Java legado (1.6 Swing) para uma arquitetura moderna com Spring Boot 4, Next.js 16 e PostgreSQL 16. Implementa microserviços, CI/CD automatizado e interface web contemporânea para gestão de escrituras e documentação notarial.

Instalação

$npx convez-ai matiaspakua/notaire

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 dia
Versão
v0.4.1
Issues abertas
169
Contribuidores
3

Casos de uso

  • Modernização de sistemas legados em Java para arquiteturas em nuvem
  • Implementação de CI/CD e automação de deploy com Docker e GitHub Actions
  • Desenvolvimento full-stack com Spring Boot backend e Next.js frontend
  • Testes E2E automatizados e cobertura de código em projetos migrados

Veredito

Projeto maduro e bem arquitetado para quem busca padrões de migração de legado. Excelente referência de CI/CD, testes automatizados e estrutura multi-camadas; demanda conhecimento sólido em Java, Spring, DevOps e ecossistema moderno.

README

A tradução para o português deste README ainda está na fila.

📜 Notaire — Modernización de Sistema de Gestión para Escribanía

Java Spring Boot Next.js React PostgreSQL Docker TypeScript Tailwind CSS

CI - Build & Test CD - Docker PR Validation Frontend CI Playwright E2E Trivy Coverage License: MIT

De un monolito Java 1.6 Swing a microservicios modernos con Spring Boot 4, Next.js 16 y Postgres 16.

Una migración completa con trazabilidad total, CI/CD automatizado, y un ecosistema multi-cliente.


📋 Tabla de Contenidos


🎯 Visión del Proyecto

El Problema Original

El sistema original era un monolito Java 1.6 con Swing que había servido fielmente durante más de una década en una escribanía. Con el tiempo, acumuló deuda técnica crítica:

  • 🔗 Acoplamiento extremo entre lógica de negocio, acceso a datos e interfaz gráfica
  • 🐘 Base de datos MySQL 5 sin control de versiones ni migraciones
  • 🔒 Password hashing con MD5 — vulnerable y sin posibilidad de migración gradual
  • 📦 Sin contenedores — deployment manual, sin reproducibilidad
  • 🧪 Cero tests automatizados — cada cambio era un riesgo
  • 🖥️ Solo desktop — sin acceso remoto ni web

La Solución

Notaire es el resultado de una migración completa hacia una arquitectura moderna:

  • Backend: API REST con Spring Boot 4.0.6 y Java 21
  • Frontend Moderno: Next.js 16 con React 19, TypeScript y Tailwind CSS 4
  • Cliente Transicional: Swing refactorizado como REST client (coexistencia durante la migración)
  • Base de Datos: PostgreSQL 16 con Flyway para migraciones versionadas
  • Infraestructura: Contenedores Docker con multi-stage builds optimizados
  • Observabilidad: Micrometer + Prometheus + Loki/Grafana
  • CI/CD: 9 workflows de GitHub Actions + Jenkins

Filosofía: Cada línea de código nuevo está testeada. Cada migración está documentada en un ADR. Cada cambio tiene trazabilidad completa desde el caso de uso hasta el commit.

Estado Actual

FaseEstadoDetalle
🏗️ Backend API✅ Completo26 controllers REST, 27 repositorios Spring Data JPA, 30 entidades
🖥️ Cliente Swing Transicional✅ CompletoSwing refactorizado como REST client
📱 Frontend Next.js✅ Completo27 páginas, 20 hooks personalizados, Apple Design System
🗄️ Base de Datos✅ CompletoPostgreSQL 16, Flyway versionado, scripts init-db
🧪 Testing✅ CompletoUnitarios + Integración + E2E Playwright + Swing E2E
📊 Observabilidad✅ CompletoPrometheus + Loki + Grafana + structured logging
🌐 Internacionalización✅ En progresoi18n con next-intl, multi-idioma
🔄 CI/CD✅ Completo9 workflows, quality gates, Docker publish

🏗️ Arquitectura del Sistema

Diagrama de Alto Nivel

flowchart TD
  %% ── STYLE DEFINITIONS ──
  classDef client fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#01579b
  classDef backend fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#e65100
  classDef data fill:#e8f5e9,stroke:#388e3c,stroke-width:2px,color:#1b5e20
  classDef infra fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
  classDef security fill:#ffebee,stroke:#d32f2f,stroke-width:2px,color:#b71c1c
  classDef observ fill:#e8eaf6,stroke:#3949ab,stroke-width:2px,color:#1a237e

  %% ── USER / CLIENTS ──
  subgraph CLIENTES ["📱 Clientes"]
    direction LR
    NEXT["Next.js 16<br/>React 19 · Tailwind CSS 4<br/>TypeScript 5.7"]:::client
    SWING["Swing (Legacy)<br/>REST Client<br/>Transicional"]:::client
  end

  BROWSER["🌐 Navegador / Usuario<br/>:3000"]:::client

  %% ── BACKEND ──
  subgraph BACKEND ["⚙️ Backend API — Spring Boot 4.0.6 · Java 21 · :8080"]
    direction TB

    subgraph API ["API Layer"]
      CTRL["26 REST Controllers<br/>/api/v1/*"]:::backend
    end

    subgraph SERVICE ["Business Logic"]
      SVC["5 Services<br/>Escritura · Persona · Pago<br/>Presupuesto · Auditoría"]:::backend
    end

    subgraph REPO ["Data Access"]
      REPOS["27 Spring Data JPA<br/>Repositories"]:::backend
      JPACTL["26 Legacy JpaControllers<br/>(Puente de migración)"]:::backend
    end

    subgraph ENT ["Domain Model"]
      ENTITIES["30 JPA Entities<br/>Negocio package"]:::backend
    end

    subgraph CROSS ["🔄 Cross-Cutting"]
      SEC["Security<br/>BCrypt · CORS · Auth"]:::backend
      OBS["Observability<br/>Micrometer · Prometheus<br/>Tracing · Structured Logging"]:::observ
      EXC["Exception Handling<br/>@ControllerAdvice<br/>ErrorResponse"]:::security
      AUDIT["Auditoría AOP<br/>AuditoriaAspect<br/>(AspectJ)"]:::backend
      FLYWAY["Flyway Migrations<br/>V1 · V2"]:::backend
      JASPER["JasperReports<br/>PDF Generation"]:::backend
    end
  end

  %% ── DATABASE ──
  subgraph DB ["🗄️ Base de Datos"]
    PG["PostgreSQL 16<br/>HikariCP Pool (min:5, max:20)<br/>init-db + Flyway"]:::data
  end

  %% ── INFRASTRUCTURE ──
  subgraph INFRA ["☁️ Infraestructura"]
    DOCKER["Docker Compose<br/>Multi-stage builds"]:::infra
    GHACT["GitHub Actions<br/>9 workflows"]:::infra
    JENKINS["Jenkins Pipeline"]:::infra
    PGADMIN["pgAdmin 4<br/>:5050"]:::infra
    TRIVY["Trivy Security<br/>Vulnerability Scanner"]:::infra
    PROM["Prometheus<br/>Metrics"]:::infra
    GRAFANA["Loki / Grafana<br/>Logs & Dashboards"]:::infra
    PLAYWRIGHT["Playwright E2E<br/>Multi-browser Tests"]:::infra
    BRUNO["Bruno API Tests<br/>Colecciones HTTP"]:::infra
  end

  %% ── EDGES ──
  BROWSER -->|"HTTP :3000"| NEXT
  BROWSER -.->|"Legacy Access"| SWING
  NEXT -->|"Proxy Rewrite<br/>${BACKEND_URL}/api/v1/*"| CTRL
  SWING -.->|"REST Calls"| CTRL
  CTRL --> SVC
  SVC --> REPOS
  SVC -.->|"Legacy Bridge"| JPACTL
  REPOS --> ENTITIES
  JPACTL --> ENTITIES
  ENTITIES --> PG

  %% Cross-cutting connections
  SEC -.-> CTRL
  OBS -.-> CTRL
  OBS -.-> SVC
  EXC -.-> CTRL
  AUDIT -.-> SVC

  %% Infra connections
  DOCKER --> PG
  DOCKER --> CTRL
  DOCKER --> NEXT
  GHACT -.->|"CI/CD Orchestration"| DOCKER
  JENKINS -.->|"Alternative Pipeline"| DOCKER
  PGADMIN --> PG
  TRIVY -.-> DOCKER
  PROM -.->|"Scrape :8080/metrics"| OBS
  GRAFANA -.-> PROM
  PLAYWRIGHT -.->|"E2E against :3000"| NEXT
  BRUNO -.->|"HTTP against :8080"| CTRL

Estructura del Repositorio

notaire/
│
├── 📦 backend-api/                   # Spring Boot 4 REST API
│   ├── src/main/java/.../            #
│   │   ├── api/                      # 26 REST Controllers (/api/v1/*)
│   │   ├── service/                  # 5 Business Services
│   │   ├── repository/               # 27 Spring Data JPA Repositories
│   │   ├── negocio/                  # 30 JPA Entities (mapeo legacy)
│   │   ├── jpa/                      # 26 Legacy JPA Controllers (puente)
│   │   ├── config/                   # 7 Spring Config Classes
│   │   ├── security/                 # PasswordEncoder, Auth
│   │   ├── audit/                    # AOP Auditoría transversal
│   │   ├── observability/           # Health indicators, metrics
│   │   └── exception/               # Global error handling
│   ├── src/main/resources/
│   │   ├── db/migration/             # Flyway SQL migrations
│   │   └── reportes/                 # JasperReports (.jasper/.jrxml)
│   └── pom.xml
│
├── 🖥️ frontend-swing/                # Swing REST Client (transicional)
│   └── src/main/java/.../
│       └── gui/api/client/           # REST client para la legacy UI
│
├── 📱 frontend/                      # Next.js 16 Modern Web App
│   ├── src/
│   │   ├── app/                      # 27 Páginas (App Router)
│   │   │   ├── login/                # Autenticación
│   │   │   └── dashboard/            # 25+ páginas de gestión
│   │   ├── components/               # UI Components
│   │   │   ├── ui/                   # shadcn/ui + Radix primitives
│   │   │   ├── layout/              # AppShell, Sidebar, Header
│   │   │   └── shared/              # DataTable, ConfirmDialog
│   │   ├── hooks/                    # 20 Custom React Hooks
│   │   ├── theme/                    # Apple Design System Tokens
│   │   ├── store/                    # Zustand State Management
│   │   ├── lib/                      # API Client, utilities
│   │   └── tests/                    # Vitest Unit Tests
│   ├── tests/e2e/                    # Playwright E2E Tests
│   ├── vitest.config.ts
│   └── playwright.config.ts
│
├── 🔗 notaire-shared/                # DTOs y contratos compartidos
│
├── 🗄️ init-db/                       # Scripts PostgreSQL + init schema
│   ├── 01-schema.sql                 # DDL completo
│   └── 02-data.sql                   # Datos iniciales
│
├── 🐳 docker-compose.yml             # Orquestación multi-servicio
├── 🐳 Dockerfile.backend             # Multi-stage build
├── 📱 frontend/Dockerfile            # Next.js standalone build
│
├── 📚 docs/                          # Documentación completa
│   ├── 01-business/                  # Requisitos, Casos de Uso (73 CUs)
│   ├── 02-architecture/              # 11 ADRs, SAD, SARs
│   ├── 03-development/              # Guías de setup y testing
│   ├── 04-operations/               # CI/CD, Seguridad
│   ├── 05-api/                      # OpenAPI specs
│   └── 06-learning/                 # Onboarding
│
├── .github/workflows/                # 9 GitHub Actions workflows
├── infra/                            # Terraform/Ansible (planeado)
├── scripts/                          # Bash scripts de utilidad
│
├── .claude/                          # AI Agent configuration
│   ├── rules/                        # Workflow y reglas de código
│   └── skills/                       # Skills especializados
│
├── opencode.json                     # OpenCode AI config
├── CLAUDE.md                         # Claude Code instructions
├── AGENTS.md                         # AI agent coding guidelines
└── checkstyle.xml                    # Code style rules

Stack Tecnológico Completo

CapaTecnologíaVersiónPropósito
RuntimeJava21 LTSPlataforma principal del backend
Framework BackendSpring Boot4.0.6IoC, REST, Data JPA, Security, Actuator
API DocumentationSpringDoc OpenAPI3.0.3Swagger UI interactiva
ORMSpring Data JPA / Hibernate—Persistencia y acceso a datos
Base de DatosPostgreSQL16Base de datos relacional principal
Migration DBFlyway—Migraciones versionadas de schema
Connection PoolHikariCP—Pool de conexiones JDBC
JSONJackson—Serialización JSON
PDFJasperReports3.5.3Generación de reportes PDF
Testing BackendJUnit 5 + Mockito—Tests unitarios y de integración
Testing ContainersTestcontainers2.0.5PostgreSQL en contenedor para tests
CoverageJaCoCo0.8.14Análisis de cobertura (80% min.)
Static AnalysisSpotBugs4.9.8Detección de bugs estáticos
Code StyleCheckstyle—Estilo de código Google
ObservingMicrometer + Prometheus—Métricas y monitoreo
TracingMicrometer Tracing (Brave)—Distributed tracing (W3C)
LoggingLogstash Logback Encoder9.0Logging estructurado JSON
SecuritySpring Security + BCrypt—Autenticación y encriptación
VulnerabilityTrivy—Escaneo de vulnerabilidades
Frontend RuntimeNode.js22Runtime del frontend
Frontend FrameworkNext.js16React metaframework (App Router)
UI LibraryReact19Componentes de interfaz
LanguageTypeScript5.7Tipado estático
CSSTailwind CSS4.0Utility-first CSS
State ManagementZustand5.0Estado global liviano
Server StateTanStack React Query5.62Cache y fetching de datos
Component Libraryshadcn/ui + Radix—Primitivas accesibles
IconsLucide React0.468Iconografía SVG
NotificationsSonner1.7Toast notifications
Testing FrontendVitest4.1Tests unitarios React
E2E TestingPlaywright1.49Tests end-to-end multi-browser
Testing Library@testing-library/react16Testing de componentes
Design TokensTheme System (custom)—Sistema de diseño Apple
i18nnext-intl—Internacionalización
Container EngineDocker—Contenedores
OrquestaciónDocker Compose—Multi-servicio local
CI/CDGitHub Actions—9 workflows automatizados
CI/CDJenkins—Pipeline alternativo
RegistryGitHub Container Registry—Docker images
AI Agent (OpenCode)OpenCode—Desarrollo asistido por IA
AI Agent (Claude)Claude Code—Code review + desarrollo
API TestingBruno—Colecciones de tests HTTP
E2E SwingRobot Framework—Tests de UI legacy

🚀 Inicio Rápido

Prerrequisitos

# Backend
Java 21+          # Temurin o OpenJDK recomendado
Maven 3.9+
Docker + Compose # Para ejecución containerizada

# Frontend (desarrollo local)
Node.js 22+
npm 10+

Ejecución con Docker (Recomendado)

# 1. Clonar
git clone https://github.com/matiaspakua/notaire.git
cd notaire

# 2. Variables de entorno
cp .env.example .env
# Editar según sea necesario

# 3. Iniciar todo (PostgreSQL + Backend + Frontend + pgAdmin)
bash scripts/start.sh

# 4. Verificar estado
bash scripts/health.sh

Ejecución en Desarrollo

# Terminal 1: Backend
cd backend-api && mvn spring-boot:run -Dspring-boot.run.profiles=dev

# Terminal 2: Frontend
cd frontend && npm run dev

# Terminal 3: Base de datos (si no usás Docker Compose)
# Asegurate de tener PostgreSQL 16 corriendo en :5432

Servicios Disponibles

ServicioURLPropósito
🌐 Backend APIhttp://localhost:8080API REST
📖 Swagger UIhttp://localhost:8080/swagger-ui.htmlDocumentación interactiva
💚 Health Checkhttp://localhost:8080/actuator/healthHealth + Liveness + Readiness
📊 Prometheushttp://localhost:8080/actuator/metricsMétricas de aplicación
🖥️ Frontendhttp://localhost:3000Web App Next.js
🗄️ pgAdminhttp://localhost:5050Admin DB (admin@notaire.com / admin)

📊 Métricas del Proyecto

MétricaValorDetalle
Commits totales339+Desde febrero 2026
Contribuidores32 desarrolladores + Dependabot
Controllers REST26Endpoints /api/v1/*
Spring Data Repos27Interfaces JpaRepository
Entidades JPA30Modelo de dominio
Servicios5Lógica de negocio
Clases de Config7Security, JPA, OpenAPI, etc.
Páginas Frontend27Dashboard + Login
React Hooks20Custom hooks por módulo
DTOs Compartidos54+Contrato entre módulos
Casos de Uso73Trazabilidad completa
ADR11Architecture Decision Records
Workflows CI/CD9GitHub Actions
Módulos Maven3backend-api, frontend-swing, notaire-shared

Líneas de Código

Lenguaje        Archivos  Líneas
─────────────────────────────────
Java (backend)     210+    ~18,000
TypeScript (front)  180+   ~15,000
SQL (migrations)    20+    ~2,500
XML/YAML config     30+    ~1,500
Total               440+   ~37,000+

Cobertura de Código

MóduloCobertura LíneasCobertura BranchesEstado
backend-api~29% (objetivo 80%)~15% (objetivo 80%)⚙️ Piso mínimo aplicado por JaCoCo (mvn verify), con ratchet ascendente

Ciclo de Vida del Proyecto

gitGraph
   commit id: "init: project skeleton" tag: "v0.1"
   branch swing-migration
   commit id: "feat: form migrations"
   commit id: "feat: API swing client"
   commit id: "test: E2E Swing tests"
   checkout main
   merge swing-migration
   branch backend-core
   commit id: "feat: Spring Boot API"
   commit id: "feat: JPA entities + repos"
   commit id: "feat: Flyway migrations"
   commit id: "feat: security (BCrypt)"
   commit id: "fix: OptimisticLockException"
   checkout main
   merge backend-core
   branch frontend-next
   commit id: "feat: Next.js 15 init"
   commit id: "feat: Apple design system"
   commit id: "feat: 27 dashboard pages"
   commit id: "test: Vitest + Playwright"
   checkout main
   merge frontend-next
   branch observability
   commit id: "feat: Micrometer + Prometheus"
   commit id: "feat: structured logging"
   commit id: "feat: DevOps observability"
   checkout main
   merge observability
   branch l10n
   commit id: "feat: next-intl i18n"
   commit id: "feat: E2E l10n tests"
   checkout main
   merge l10n

🧪 Estrategia de Testing

Pirámide de Testing

                    ╱╲
                   ╱  ╲
                  ╱ E2E ╲           ← Playwright (Chrome + multi-browser)
                 ╱  27 tests ╲         Swing Robot Framework (89 tests)
                ╱──────────────╲
               ╱                ╲
              ╱  Integration     ╲    ← Spring Boot Test + Testcontainers
             ╱  20+ tests         ╲     H2 (offline) + PostgreSQL (Docker)
            ╱──────────────────────╲
           ╱                        ╲
          ╱      Unit Tests           ╲ ← JUnit 5 + Mockito (backend)
         ╱      80+ tests              ╲   Vitest + Testing Library (frontend)
        ╱────────────────────────────────╲
       ╱                                  ╲
      ╱   Static Analysis + Quality Gates   ╲ ← JaCoCo (80%), SpotBugs,
     ╱     Checkstyle, Trivy Security         ╲   PR Validation
    ╱────────────────────────────────────────────╲

Ejecutar Tests

# ────── BACKEND ──────

# Todos los tests backend
mvn test -pl backend-api

# Tests unitarios
mvn test -pl backend-api -Dtest="**/unit/*"

# Tests de integración
mvn test -pl backend-api -Dtest="**/integration/*"

# Cobertura
mvn test -pl backend-api && mvn jacoco:report -pl backend-api
# Reporte HTML: backend-api/target/site/jacoco/index.html

# Test específico
mvn test -pl backend-api -Dtest=PresupuestoServiceTest

# ────── FRONTEND ──────

# Tests unitarios (Vitest)
cd frontend && npm test

# Tests con cobertura
cd frontend && npm run test:coverage

# Tests E2E (Playwright)
cd frontend && npm run test:e2e

# ────── API TESTS ──────

# Tests HTTP con Bruno (requiere API corriendo)
bash scripts/test.sh

# ────── TODO ──────

# Verificación completa
mvn verify -pl backend-api

🚦 CI/CD y Calidad

Workflows de GitHub Actions

WorkflowEventoPropósito
CI - Build & Testpush / PR a mainCompila, tests unitarios, integración, cobertura, seguridad, Docker
CD - Dockerpush a mainBuild + push de imagen Docker a GitHub Container Registry
PR ValidationPR a mainValida Conventional Commits, estilo, tests
Frontend CIpush / PRBuild Next.js, lint, tests Vitest
Playwright E2Epush a mainSuite completa E2E multi-browser
E2E Swingpush / PRTests de UI legacy con Robot Framework
Claude CodePRCode review automático con IA
OpenCode—Configuración del agente de desarrollo

Puertas de Calidad

GateThresholdHerramienta
✅ Tests unitarios100% passingJUnit 5 + Surefire
✅ Tests integración100% passingSpring Boot Test
⚙️ Cobertura de líneapiso ~28% (objetivo 80%)JaCoCo (ratchet)
⚙️ Cobertura de branchespiso ~14% (objetivo 80%)JaCoCo (ratchet)
✅ Vulnerabilidades críticas0Trivy
✅ Code styleSin violacionesCheckstyle (Google Style)
✅ Bug detectionSin erroresSpotBugs (Max effort)
✅ Commits convencionalesFormato válidosemantic-pull-request
✅ Build DockerExitosoDocker Buildx

🔍 Observabilidad y Monitoreo

Stack de Observabilidad

ComponenteTecnologíaPropósito
📊 MétricasMicrometer + PrometheusMétricas JVM, HTTP, personalizadas
🔗 TracingMicrometer Tracing (Brave) + ZipkinDistributed tracing (W3C propagation)
📝 LoggingLogstash Logback EncoderLogging estructurado en JSON
📈 DashboardsGrafana + Loki (planeado)Visualización de métricas y logs
💚 HealthSpring Boot ActuatorLiveness + Readiness + Health probes

Métricas Expuestas

# Endpoints de Actuator disponibles:
/actuator/health            # Health check (liveness + readiness)
/actuator/metrics           # Todas las métricas
/actuator/prometheus        # Formato Prometheus
/actuator/info              # Información de build
/actuator/threaddump        # Thread dump
/actuator/heapdump          # Heap dump
/actuator/env               # Environment properties
/actuator/loggers           # Log levels configurables

# Principales métricas expuestas:
# - jvm.memory.*            # Uso de memoria heap y no-heap
# - jvm.gc.*                # Garbage collection stats
# - jvm.threads.*           # Estados de threads
# - http.server.requests    # HTTP request metrics (percentiles: 10ms-2s)
# - process.*               # CPU, uptime
# - logback.*               # Log events por nivel

🛡️ Seguridad

Medidas Implementadas

MedidaEstadoDetalle
🔐 Password Hashing✅ BCrypt (strength=12)Migrado desde MD5 legacy
🚫 CORS✅ ConfiguradoOrígenes permitidos: localhost:3000, :8080, :9090
🛡️ Spring Security✅ ActivoProtección de endpoints de Actuator
🔍 Trivy Scanning✅ CI pipelineEscaneo de vulnerabilidades en cada build
📝 Input Validation✅ Spring Validation@Valid, @NotNull, @Size, etc.
⚠️ Error Handling✅ Global@ControllerAdvice con ErrorResponse estandarizado
🐳 Non-root container✅ DockerUsuario notary sin privilegios
🔒 JVM flags✅ OptimizadosUseContainerSupport, MaxRAMPercentage=70%

🎨 Frontend Moderno (Next.js 16)

Sistema de Diseño Apple-Inspired

El frontend implementa un sistema de diseño completo inspirado en macOS Sequoia / iOS 18, con tokens de diseño centralizados:

// frontend/src/theme/tokens.ts — Fuente única de verdad

// Paleta de colores Apple: San Francisco
colors.neutral[900]   // #1D1D1F — Casi negro (texto)
colors.primary[600]   // #0071E3 — Apple Blue
colors.success[500]   // #34C759 — Apple Green
colors.warning[500]   // #FF9500 — Apple Orange
colors.error[500]     // #FF453A — Apple Red

// Tipografía: SF Pro
typography.fontFamily.display  // "SF Pro Display", —system-ui, sans-serif
typography.fontFamily.body     // "SF Pro Text", —system-ui, sans-serif

// Sombras multi-capa Apple-style
shadows.md: "0 0 0 1px rgba(0,0,0,0.06), 0 4px 8px rgba(0,0,0,0.06), 0 16px 32px rgba(0,0,0,0.08)"

// Bordes redondeados
sizes.card.borderRadius  // 28px (2xl) — Apple cards
sizes.input.borderRadius // 12px (md)

Componentes UI: shadcn/ui sobre Radix Primitives — @radix-ui/react-dialog, @radix-ui/react-select, @radix-ui/react-tabs, @radix-ui/react-dropdown-menu, @radix-ui/react-tooltip y más. Patrones de formulario reutilizables en src/theme/form-patterns.tsx.

Estado: Zustand para UI state + TanStack React Query para server state.

Páginas Implementadas

MóduloPáginasHooks
🔑 AuthLogin—
📊 DashboardMain dashboard—
👥 PersonasList, CRUDusePersonas
📄 DocumentosList, CRUD, tiposuseDocumentos, useDocumentosPresentados
✍️ EscriturasList, CRUDuseEscrituras
📋 GestionesList, CRUD, estadosuseGestiones, useEstadosGestion
💰 PresupuestosList, CRUD, conceptosusePresupuestos, useConceptos
🏢 InmueblesList, CRUDuseInmuebles
📑 ProtocoloList, CRUD—
📒 FoliosList, CRUD, tiposuseFolios
🔄 CopiasList, CRUD, testimoniosuseCopias
💳 PagosList, CRUDusePagos
👤 SuplenciasList, CRUDuseSuplencias
📊 ReportesPDF generationuseReportes
📈 AuditoríaLogs, historialuseAuditoria, useHistorial
⚙️ AdminUsuarios, trámites, items, plantillas, conceptosuseUsuarios, useTiposTramite, useItems, usePlantillas

🤖 Ecosistema de Agentes AI

Notaire implementa un ecosistema completo de desarrollo asistido por inteligencia artificial, con agentes y herramientas configurados para maximizar la productividad:

Agentes Configurados

AgentePlataformaRol
🧠 OpenCodeLocal (opencode.json)Agente principal de desarrollo
🤖 Claude CodeCLI + GitHub ActionsCode review automático en PRs
👁️ Code ReviewerSubagente OpenCodeRevisión de seguridad y performance
🔒 Security AuditorSubagente OpenCodeAuditoría de vulnerabilidades

Skills Especializados

El proyecto incluye skills especializados para cada aspecto del desarrollo:

SkillPropósito
🏗️ ai-agent-workflowWorkflow mandatorio: Issue → Branch → PR
🧪 testingEstrategia completa de testing (unit, integration, E2E, security)
🔄 maven-buildBuild y test de módulos Maven
🎨 frontend-designSistema de diseño Apple para componentes
📊 drawioGeneración de diagramas de arquitectura
🚀 devopsCI/CD pipelines, Docker, infraestructura
📋 product-ownerUser stories, sprint planning, milestones
📐 software-functional-analystAnálisis funcional, casos de uso
☕ javaBest practices Java moderno (records, sealed, pattern matching)
🛣️ flywayMigraciones de base de datos versionadas
📡 api-restColecciones Bruno de tests API

📘 Lecciones Aprendidas y Problemas Resueltos

Esta sección documenta los problemas, decisiones y aprendizajes más significativos durante el desarrollo del proyecto.

🔴 Críticos

ProblemaSíntomaSoluciónCommit
MD5 Password HashingContraseñas almacenadas con hash MD5 (vulnerable)Migración a BCrypt con strength=12, encoder configurablec7a2132
OptimisticLockExceptionError en actualizaciones concurrentes de PlantillaPresupuestoRevisión de estrategia de locking y versionado JPA4c289ee
API 500 en POSTError 500 al crear presupuestos, personas, documentosSerialización incorrecta de JPA entities con lazy loading863417e
White-label Error PagesErrores HTTP sin formato JSONImplementación de @ControllerAdvice global con ErrorResponse8bed1b5
Lazy Loading en TestsTests de integración fallando por lazy-loading pollution@Sql cleanup y configuración open-in-view=falsec55a23f

🟡 Arquitectura y Diseño

ProblemaContextoDecisiónADR
Monolito vs MicroserviciosAplicación Swing con todo acopladoMigración progresiva: REST API primero, frontend moderno despuésADR-001
PostgreSQL vs MySQLBase legacy MySQL 5Migrar a PostgreSQL 16 con Flyway para versionadoADR-002
Spring Data JPA vs JpaControllersLegacy bridge existenteCoexistencia: nuevos features usan Spring Data, legacy migra progresivamenteADR-007
Next.js vs SPANecesidad de frontend modernoNext.js 16 App Router por SSR, SEO, y server componentsADR-005
Cliente Swing LegacyUI desktop existenteRefactorizar como REST client (no descartar, migrar gradualmente)ADR-003
Testcontainers v1→v2Breaking changes en APIMigración a BOM v2.0.5 con artifact IDs actualizados209bf38

🔵 DevOps y CI/CD

ProblemaContextoSolución
GitHub Actions flakyTests E2E fallando intermitentementecontinue-on-error en jobs no críticos, retry logic
Multi-stage DockerImagen muy grande (400MB+)Build en dos etapas: Maven builder + JRE alpine slim (~180MB)
Cobertura en CIJaCoCo check rompía el buildReport en CI, check no bloqueante, PR comment con madrapps
TestContainers en CIDependencia de Docker en CIGitHub Actions con Docker preinstalado, test via Testcontainers
PR ValidationCommits sin formato conventionalamannn/action-semantic-pull-request + linter

🟣 Frontend

ProblemaContextoSolución
Iconos rotos en DockerPNGs de la app Swing no se renderizaban en Next.jsCopiar assets al build standalone + unoptimized: true
TypeScript errorsTipos incorrectos después de migraciónStrict mode, tsconfig.json paths, tipos en hooks
Auth cookie vacíaPágina en blanco al hacer logoutClear cookie + redirect explícito
Proxy routingFrontend en Docker no llegaba al backendnext.config.ts rewrites proxy /api/v1/*
Sistema de diseñoInconsistencia visual entre páginasTheme tokens centralizados Apple-inspired + form patterns

⚪ Testing

ProblemaContextoSolución
Sin tests legacyCódigo original sin coberturaE2E tests con Robot Framework (89 tests para Swing)
Gap analysisCUs sin tests de APIMatriz CU-API gap con cobertura por use case
Bruno syntax errorsTests HTTP con formato incorrectoCorrección de sintaxis Bruno + CHAI assertions robustas
H2 vs PostgreSQLTests offline vs real DBTests de integración con Testcontainers, unitarios con H2

🟠 Dependencias y Herramientas

ProblemaVersiónAcción
Spring Boot 3→44.0.6Migración de Jakarta EE, Sleuth → Micrometer Tracing
Testcontainers2.0.5Breaking changes en API de contenedores
SpotBugs + Java 214.9.8Skip por defecto local, habilitado en CI
JaCoCo + Java 210.8.14Configuración de excludes para clases legacy
Dependabot—~30 PRs de actualización automática procesados
Logstash Encoder9.0Logging estructurado JSON para Loki

📚 Documentación

El proyecto cuenta con documentación completa y estructurada siguiendo el ciclo de vida del software (SDLC). Cada decisión, cada caso de uso y cada componente está documentado.

Estructura de Documentación

docs/
├── README.md                         # Índice general y navegación
│
├── 01-business/                      # 📋 REQUISITOS Y NEGOCIO
│   ├── 01-requirements/              # Historias de usuario (INVEST)
│   ├── 02-usecases/                  # 73 Casos de uso (Given-When-Then)
│   ├── 03-data-model/               # Modelo de datos (ERD)
│   └── 04-manuals/                   # Manuales de usuario
│
├── 02-architecture/                  # 🏛️ ARQUITECTURA
│   ├── 01-adr/                       # 11 ADRs (registros de decisión)
│   ├── 02-overview/                  # SAD + diagramas C4
│   └── 03-sar/                       # Solution Architecture Reports
│
├── 03-development/                   # 🛠️ DESARROLLO
│   ├── 01-setup/                     # Setup de entorno
│   ├── 02-build/                     # Guías de build
│   └── 03-testing/                   # Estrategia de testing
│
├── 04-operations/                    # ⚙️ OPERACIONES
│   ├── 01-cicd/                      # Pipelines CI/CD
│   ├── 02-deployment/               # Despliegue
│   └── 03-security/                  # Seguridad
│
├── 05-api/                           # 📡 API REST
│   └── openapi/                      # Especificaciones OpenAPI
│
└── 06-learning/                      # 📚 APRENDIZAJE
    └── onboarding/                   # Guías para nuevos desarrolladores

🛣️ Roadmap

HitoFechaEstado
✅ Backend REST API completoQ1 2026✅
✅ Base de datos PostgreSQL + FlywayQ1 2026✅
✅ Cliente Swing transicionalQ1 2026✅
✅ Frontend Next.js + Apple DesignQ2 2026✅
✅ Observabilidad + MonitoreoQ2 2026✅
✅ CI/CD Completo + AutomatizaciónQ2 2026✅
🔄 Internacionalización (i18n)Q2 2026🔄 En progreso
📱 Temas oscuroQ3 2026📋 Planificado
🔔 Notificaciones en tiempo realQ3 2026📋 Planificado
📱 Modo offline / PWAQ3 2026📋 Planificado
🚢 Kubernetes + Helm ChartsQ4 2026📋 Planificado
🔄 Migración completa de JpaControllersQ4 2026📋 Planificado

🤝 Contribuir

# 1. Fork → Clone → Branch
git checkout -b feat/<issue-id>_descripcion_breve

# 2. Implementar + Testear
mvn test -pl backend-api
mvn jacoco:check -pl backend-api

# 3. Commit (Conventional Commits)
git commit -m "feat(scope): descripción

Closes #<issue-id>"

# 4. Push + PR
git push -u origin feat/<issue-id>_descripcion
gh pr create --title "feat: descripción" --body "Fixes #<issue-id>"

Convenciones del Proyecto

  • Commits: Conventional Commits estrictamente
  • Branches: <type>/<issue-number>_<description> (ej: feat/253_jwt_auth)
  • Java: Google Style + Checkstyle + SpotBugs
  • TypeScript: Strict mode + tipos explícitos
  • Cobertura: Mínimo 80% (líneas + branches)
  • PRs: Todos revisados (humano + AI Code Review)

📄 Licencia

Distribuido bajo MIT License. Ver LICENSE para más detalles.


Desarrollado con ☕, 🎵 y mucha paciencia por Matías Miguez

Modernizando la escribanía del futuro, un commit a la vez.

339+ commits · 73 casos de uso · 11 ADRs · 9 workflows · 3 módulos · 1 objetivo

Ver o original no GitHub

Bom para

Relacionados