🔍 ExplainMyCodebase

Escala del Proyecto

Descripción General

Entrar en un proyecto que no conoces es el trabajo más lento de un desarrollador: averiguar qué hace cada carpeta, dónde está la lógica de negocio y por dónde empezar a leer. Si el proyecto no tiene documentación —y casi nunca la tiene— pueden irse días.

ExplainMyCodebase automatiza ese primer paso. Subes el proyecto comprimido, la herramienta lo descomprime, recorre su estructura, parsea los ficheros y genera con IA local una explicación de qué es cada módulo y cómo se relacionan. El resultado es un árbol de carpetas navegable junto al análisis.

Está construido con Next.js 14 usando App Router en el frontend y un backend Express que se encarga de la subida, la descompresión y el parseo antes de hablar con Ollama. El modelo corre en local: el código que subes no viaja a ningún proveedor externo, que es un requisito bastante razonable cuando se trata del código de tu empresa.

Tecnologías Utilizadas

Componentes y Servicios

Arquitectura

Dos aplicaciones separadas. El frontend es Next.js 14 con App Router: app/page.tsx para la subida y app/result/page.tsx para el resultado. El backend es un Express mínimo cuyo trabajo es recibir el fichero, descomprimirlo, parsearlo y orquestar las llamadas a Ollama.

La separación tiene una razón práctica: descomprimir y recorrer un proyecto grande es trabajo intensivo de disco que no encaja en una función serverless de Next.

ExplainMyCodebase/
├── backend/
│   ├── index.js            # servidor Express
│   ├── services/            # ollamaService.js
│   ├── utils/               # fileParser.js
│   ├── uploads/             # proyectos recibidos
│   └── .env.example
└── frontend/
    ├── app/page.tsx        # formulario de subida
    ├── app/result/page.tsx # resultado del análisis
    ├── app/OllamaStatusBadge.tsx
    └── components/          # FolderTree, AnalysisResult, UploadForm

Integraciones Externas

Flujo de Análisis

1. Comprobación previa: el indicador de estado verifica que Ollama esté levantado antes de permitir la subida.
2. Subida: el usuario envía el proyecto comprimido; Multer lo recibe en el backend.
3. Descompresión: adm-zip extrae el contenido en el directorio de trabajo.
4. Recorrido y parseo: fileParser construye el árbol de carpetas y lee los ficheros relevantes.
5. Generación: ollamaService construye los prompts y pide al modelo la explicación de cada módulo.
6. Presentación: el frontend muestra el árbol navegable junto al análisis generado.

Retos Técnicos y Decisiones de Diseño

El contexto de un modelo es finito

No se puede meter un proyecto entero en un prompt: cualquier repositorio real excede la ventana de contexto. El trabajo interesante está en fileParser, que decide qué leer y qué ignorar, y en trocear el análisis por módulos en lugar de intentar explicarlo todo de una vez.

IA local porque es código ajeno

La herramienta se usa sobre proyectos que no son tuyos, muchas veces de una empresa. Enviarlos a una API en la nube es exactamente lo que un acuerdo de confidencialidad prohíbe. Ollama en local convierte la herramienta en algo que se puede usar de verdad en un entorno profesional.

Avisar del estado antes de que falle

Si Ollama no está corriendo, el usuario sube un proyecto, espera y recibe un error. El OllamaStatusBadge existe para invertir ese orden: se comprueba primero y se avisa antes. Es un componente pequeño que evita el fallo más común de la herramienta.

Frontend y backend separados por una razón

Next.js podría haber hecho ambas cosas, pero descomprimir un ZIP grande y recorrerlo es un proceso largo con acceso intensivo a disco, que encaja mal con el modelo de ejecución de sus rutas de API. Un Express dedicado lo resuelve sin pelearse con el framework.

Mi Rol

Desarrollador full stack — autor único.

Frontend Next.js con App Router, backend Express, servicio de comunicación con Ollama, parser de proyectos y componentes de visualización del análisis.

Estado del Proyecto

Proyecto funcional con frontend y backend operativos. Requiere Ollama corriendo en local. La calidad del análisis depende directamente del modelo que se use.

Código y Enlaces

El código está en el repositorio Proyectos-Personales, dentro de la carpeta ExplainMyCodebase/.