AI Code Reviewer es una aplicación full-stack diseñada para enseñar arquitectura de software moderna y el uso eficiente de herramientas de IA en el desarrollo. El proyecto analiza código fuente en tiempo real utilizando herramientas de análisis estático profesionales.

• Demostrar Arquitectura Hexagonal (Ports & Adapters) en un proyecto real
• Aplicar Java 21 features (Records, Virtual Threads, Pattern Matching)
• Implementar análisis paralelo con Virtual Threads
• Integrar herramientas de análisis estático (SpotBugs, PMD, Checkstyle)
• Construir UI moderna con React 19 y Tailwind CSS 4

Este proyecto fue desarrollado como parte del Workshop: Arquitectura y Diagramas con IA de AI Dev Lab.

Contenido del Workshop:

• Diseño de arquitectura con IA (Claude/ChatGPT)
• Generación de diagramas UML con Cursor AI
• Creación de presentaciones con Gamma AI
• Buenas prácticas de documentación técnica

• Detección de vulnerabilidades con SpotBugs 4.8.3.1
• Identificación de patrones inseguros
• Sugerencias de corrección

• Detección de bottlenecks con PMD 3.21.2
• Identificación de código ineficiente
• Recomendaciones de optimización

• Validación de convenciones con Checkstyle 3.3.1
• Verificación de estándares (Google Style Guide)
• Sugerencias de mejora de legibilidad

Backend:

• ☕ Java 21 - Records, Virtual Threads, Sealed Interfaces
• 🍃 Spring Boot 3.5.9 - Framework empresarial
• 🏗️ Arquitectura Hexagonal - Separación de capas clara
• 🧵 Virtual Threads - Concurrencia ligera y eficiente
• 📊 Maven - Gestión de dependencias

Frontend:

• ⚛️ React 19.2 - Biblioteca UI moderna
• ⚡ Vite 7.x - Build tool ultra-rápido
• 🎨 Tailwind CSS 4 - Utility-first CSS
• 🎭 Framer Motion - Animaciones fluidas
• 🎯 Lucide Icons - Iconos modernos

Antes de comenzar, asegúrate de tener instalado:

• ☕ Java 21+ (OpenJDK o Oracle JDK)
• 📦 Node.js 20.19+ y npm 10+ (Descargar)
• 🔧 Maven 3.9+ (incluido en el proyecto via wrapper)
• 🔀 Git (Descargar)

# Verificar Java
java -version  # Debe mostrar Java 21+

# Verificar Node.js
node -v  # Debe mostrar v20.19+
npm -v   # Debe mostrar v10+

# Verificar Git
git --version

# 1. Clonar el repositorio
git clone https://github.com/Irina-Ichim/ai-code-reviewer-practice.git
cd ai-code-reviewer-practice

# 2. Iniciar Backend (Terminal 1)
cd backend
./mvnw clean install      # Windows: .\mvnw.cmd clean install
./mvnw spring-boot:run    # Windows: .\mvnw.cmd spring-boot:run

# 3. Iniciar Frontend (Terminal 2)
cd frontend
npm install
npm run dev

URLs:

• 🌐 Frontend: http://localhost:5173
• 🔌 Backend API: http://localhost:8080/api
• 💚 Health Check: http://localhost:8080/api/health

Ver docs/setup.md para instrucciones paso a paso con troubleshooting.

El proyecto sigue Arquitectura Hexagonal (también conocida como Ports and Adapters), que garantiza:

• ✅ Independencia del dominio - Lógica de negocio sin dependencias externas
• ✅ Testabilidad - Fácil de probar sin frameworks
• ✅ Flexibilidad - Fácil cambiar implementaciones
• ✅ Mantenibilidad - Separación clara de responsabilidades

backend/src/main/java/com/aicodereview/
├── domain/                    # 🎯 Capa de Dominio (Lógica de Negocio)
│   ├── model/                # Records inmutables
│   │   ├── AuditRequest.java
│   │   ├── AuditResponse.java
│   │   └── AuditResult.java
│   ├── port/                 # Interfaces (Puertos)
│   │   ├── AuditService.java
│   │   └── CodeAnalyzer.java
│   └── service/              # Orquestación
│       └── AuditOrchestrator.java
│
├── infrastructure/            # 🔧 Capa de Infraestructura (Adaptadores)
│   ├── adapter/              # Implementaciones de análisis
│   │   ├── SecurityAnalyzer.java
│   │   ├── PerformanceAnalyzer.java
│   │   └── StyleAnalyzer.java
│   └── config/               # Configuración Spring
│       ├── AnalyzerConfig.java
│       └── CorsConfig.java
│
└── application/               # 🌐 Capa de Aplicación (Entrada)
    └── controller/
        └── AuditController.java

frontend/src/
├── components/               # Componentes React
│   ├── CodeEditor.jsx       # Editor Monaco
│   ├── ResultCard.jsx       # Tarjeta de resultado individual
│   ├── ResultsSection.jsx   # Contenedor de resultados
│   └── LoadingSpinner.jsx   # Indicador de carga
│
├── services/                 # Servicios HTTP
│   └── auditService.js      # Cliente API
│
├── App.jsx                   # Componente raíz
├── App.css                   # Estilos globales
├── index.css                 # Tailwind base
└── main.jsx                  # Entry point

sequenceDiagram
    participant User
    participant Frontend
    participant Controller
    participant Orchestrator
    participant Analyzers
    
    User->>Frontend: Pega código y click "Analizar"
    Frontend->>Controller: POST /api/audit
    Controller->>Orchestrator: auditCode(request)
    
    Note over Orchestrator: Crea Virtual Thread Executor
    
    par Análisis Paralelo
        Orchestrator->>Analyzers: SecurityAnalyzer
        Orchestrator->>Analyzers: PerformanceAnalyzer
        Orchestrator->>Analyzers: StyleAnalyzer
    end
    
    Analyzers-->>Orchestrator: 3 AuditResults
    Orchestrator-->>Controller: AuditResponse
    Controller-->>Frontend: JSON Response
    Frontend->>User: Muestra 3 ResultCards

La documentación incluye 7 diagramas Mermaid interactivos:

📖 Ver documentación completa: Architecture Documentation

// ❌ ANTES: POJO tradicional (50+ líneas)
public class AuditRequest {
    private final String code;
    private final String language;
    // + constructor, getters, equals, hashCode, toString...
}

// ✅ AHORA: Record (3 líneas)
public record AuditRequest(
    @NotBlank String code,
    @NotNull String language
) {}

// Ejecución paralela de 3 analyzers sin overhead de threads tradicionales
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    var securityFuture = executor.submit(() -> securityAnalyzer.analyze(code));
    var performanceFuture = executor.submit(() -> performanceAnalyzer.analyze(code));
    var styleFuture = executor.submit(() -> styleAnalyzer.analyze(code));
    
    // Esperar resultados (no bloquea threads del SO)
    results.add(securityFuture.get());
    results.add(performanceFuture.get());
    results.add(styleFuture.get());
}

Ventajas:

• 🚀 Millones de threads virtuales vs miles de threads tradicionales
• 💡 Código más simple que CompletableFuture
• 🔄 Mejor para operaciones I/O-bound

// Preparado para pattern matching en switch expressions
return switch (analysisType) {
    case "SECURITY" -> new SecurityAnalyzer();
    case "PERFORMANCE" -> new PerformanceAnalyzer();
    case "STYLE" -> new StyleAnalyzer();
    default -> throw new IllegalArgumentException("Unknown type");
};

# Backend - Tests unitarios y de integración
cd backend
./mvnw test

# Frontend - Tests con Vitest (próximamente)
cd frontend
npm test

Cobertura objetivo: 70%+ en lógica de negocio

Analiza código y retorna resultados.

Request:

{
  "code": "public class Example { ... }",
  "language": "java"
}

Response:

{
  "results": [
    {
      "analysisType": "SECURITY",
      "issues": ["Potential SQL injection", "..."],
      "score": 75,
      "suggestions": ["Use PreparedStatement", "..."]
    },
    {
      "analysisType": "PERFORMANCE",
      "issues": ["Inefficient loop", "..."],
      "score": 80,
      "suggestions": ["Use Stream API", "..."]
    },
    {
      "analysisType": "STYLE",
      "issues": ["Missing Javadoc", "..."],
      "score": 85,
      "suggestions": ["Add class documentation", "..."]
    }
  ],
  "overallScore": 80,
  "timestamp": "2026-01-11T10:30:00"
}

Health check del backend.

Response:

{
  "status": "UP",
  "timestamp": "2026-01-11T10:30:00"
}

• Propósito: Detección de bugs y vulnerabilidades de seguridad
• Configuración: Effort=Max, Threshold=Low
• Output: XML Report

• Propósito: Análisis de calidad y performance
• Configuración: minimumTokens=100, targetJdk=21
• Output: XML Report

• Propósito: Validación de estilo (Google Style Guide)
• Configuración: google_checks.xml
• Output: Console + XML Report

Ver docs/tools-documentation.md para configuración detallada.

Este es un proyecto educativo. Las contribuciones son bienvenidas para:

• 🐛 Reportar bugs
• 💡 Sugerir nuevas features
• 📝 Mejorar documentación
• ✅ Añadir tests

1. Fork el proyecto
2. Crea una rama: git checkout -b feature/nueva-feature
3. Commit cambios: git commit -m 'feat: añadir nueva feature'
4. Push a la rama: git push origin feature/nueva-feature
5. Abre un Pull Request

Convenciones:

• Commits: Conventional Commits
• Código: Google Java Style Guide + ESLint

1. Claridad > Optimización Prematura

   • Código legible y autodocumentado
   • Nombres descriptivos

2. Funcionalidad > Arquitectura Perfecta

   • Soluciones pragmáticas
   • Evitar sobre-ingeniería

3. Código Educativo > Código Complejo

   • Ejemplos claros de patrones
   • Comentarios explicativos

4. Herramientas Reales > Hardcoding

   • Integración con SpotBugs/PMD/Checkstyle
   • No algoritmos inventados

❌ POJOs tradicionales → Usar Records
❌ CompletableFuture → Usar Virtual Threads
❌ Lógica en controllers → Solo delegación
❌ Componentes de clase → Solo funcionales
❌ Hardcodear análisis → Integrar herramientas

• Arquitectura Hexagonal
• Backend con Java 21
• Frontend con React 19
• Análisis mock (sin herramientas reales)
• Documentación completa

• Integración con SpotBugs
• Integración con PMD
• Integración con Checkstyle
• Parser de reportes XML

• Soporte multi-lenguaje (Python, JavaScript)
• Historial de análisis
• Comparación de resultados
• Export a PDF/Markdown

• Autenticación (JWT)
• Rate limiting
• Caché de resultados
• Métricas (Micrometer)
• Deployment (Docker + Kubernetes)

Este proyecto es para fines educativos y está disponible bajo la licencia MIT.

MIT License

Copyright (c) 2026 AI Code Reviewer Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Desarrollado por: Irina Ichim

Workshop: AI Dev Lab - Arquitectura y Diagramas con IA

Agradecimientos:

• Contribuidores del workshop
• Herramientas de IA utilizadas: Cursor AI, Claude, ChatGPT

• 📖 Documentación Completa
• 🎓 Workshop Original
• 🐙 Repositorio GitHub
• 💬 Reportar Issues

Si tienes preguntas sobre el proyecto o el workshop:

1. Revisa la documentación
2. Busca en Issues
3. Abre un nuevo Issue con la etiqueta question