DevMind — Frontend

DevMind convierte un repositorio de código en un asistente técnico con contexto. Sube un proyecto en formato .zip, deja que DevMind lo analice y haz preguntas sobre su funcionamiento. Las respuestas incluyen referencias a las partes relevantes del código para que puedas comprobarlas y seguir investigando.

Web: https://devmind-frontend.vercel.app/

Features

• Análisis de proyectos: sube repositorios en formato .zip e indexa su código.
• Chat con contexto: pregunta sobre el proyecto y recibe respuestas basadas en él.
• Fuentes verificables: consulta los fragmentos de código que respaldan cada respuesta.
• Progreso visible: sigue el estado de la indexación en tiempo real.
• Historial persistente: guarda proyectos y conversaciones con una cuenta registrada.

Cómo se usa

Crear proyecto → Subir ZIP → Indexar el código → Preguntar a la IA → Consultar fuentes e historial

Puedes empezar como invitado, sin pasar primero por un registro. Las sesiones de invitado permiten completar el flujo principal, aunque sus datos son temporales y no guardan historial. Al crear una cuenta, los proyectos y las conversaciones pasan a ser persistentes.

Los proyectos creados como invitado no se transfieren a una cuenta nueva porque el backend todavía no ofrece esa operación.

Desarrollo local

Este frontend está construido con React, Vite y TypeScript. Utiliza React Router, TanStack Query y Tailwind CSS, y consume la API descrita en docs/openapi.yaml.

Arranque rápido

npm install
npm run dev

La app queda en http://localhost:5173 (puerto por defecto de Vite, ya permitido por el CORS del backend).

Variable de entorno

La URL base de la API se configura con VITE_API_URL (por defecto http://localhost:3000). Para cambiarla, copia el ejemplo y edítalo:

cp .env.example .env
# VITE_API_URL=http://localhost:3000

Scripts

Script	Qué hace
npm run dev	Arranca el servidor de desarrollo (Vite).
npm run build	Comprueba tipos (tsc) y genera el build de producción.
npm run preview	Sirve el build de producción localmente.
npm run gen:api	Regenera los tipos de la API desde docs/openapi.yaml.

Detalles de funcionamiento

Sesión invitado vs registrado

El frontend siempre tiene un token para llamar a la API:

• Al cargar, si no hay token guardado, se crea una sesión de invitado en segundo plano (POST /auth/guest). El visitante entra directo al producto, sin ver nunca un login primero.
• Registro / login viven en páginas aparte (/register, /login) accesibles desde la cabecera. Al completarlas, el modo pasa a registered.
• El modo (guest | registered) y el token se guardan en localStorage; el frontend sabe en qué modo está sin preguntárselo al backend.
• Ante un 401, se renueva automáticamente la sesión de invitado y se reintenta la petición; si el usuario estaba registrado, se le lleva al login.
• Invitado: puede subir, indexar y preguntar, pero sus datos son temporales y no se le guarda historial. Registrado: sus proyectos persisten y tiene historial navegable.

El proyecto subido como invitado no se transfiere a la cuenta al registrarse (el backend no lo soporta), y así se indica en la UI.

Lo primero que se ve es el formulario de creación del proyecto (no un login). El nombre y la descripción se piden aquí porque son los datos que la API necesita para crear el proyecto (POST /projects); la subida del .zip ocurre ya dentro del proyecto (POST /projects/{id}/upload).

Arquitectura frontend

flowchart LR
    U[Usuario] --> UI[Páginas y componentes]
    UI --> H[Hooks de dominio]
    H --> Q[TanStack Query]
    Q --> E[Endpoints tipados]
    E --> C[Cliente HTTP]
    C --> API[API de DevMind]
    A[AuthContext] --> UI
    A --> C
    A <--> S[(Sesión en localStorage)]

Loading

Integración con OpenAPI

El archivo docs/openapi.yaml es el contrato compartido con el backend: describe los endpoints, los cuerpos de las peticiones, las respuestas, los errores y los esquemas de datos de DevMind.

La integración sigue este flujo:

1. npm run gen:api ejecuta openapi-typescript sobre el contrato.
2. La herramienta genera src/api/schema.ts; este archivo no se edita a mano.
3. src/api/types.ts expone alias de dominio —como Project, ProjectFile o AskProjectQuestionResult— a partir de los esquemas generados.
4. Los endpoints, hooks y componentes consumen esos tipos durante la compilación.

docs/openapi.yaml → openapi-typescript → schema.ts → types.ts → aplicación

Así, un cambio incompatible en un esquema se detecta al regenerar los tipos y ejecutar npm run build, antes de llegar al navegador. El contrato sigue siendo la fuente de verdad y se evita mantener modelos TypeScript duplicados que podrían quedar desincronizados.

Las funciones de src/api/endpoints.ts conservan una capa pequeña y explícita sobre fetch: construyen las rutas y peticiones, mientras que src/api/client.ts centraliza el token Bearer, la serialización, los errores y la recuperación ante respuestas 401. Actualmente, las rutas y los cuerpos de petición se implementan manualmente; la generación automática se aplica a los tipos del contrato.

Cuando cambie la API:

npm run gen:api
npm run build

El primer comando actualiza los tipos y el segundo comprueba la integración y genera el build de producción.

Estructura

src/
├── api/            Cliente de API tipado (schema generado del OpenAPI + fetch con token)
│   ├── schema.ts   Tipos autogenerados (no editar a mano; usar `npm run gen:api`)
│   ├── client.ts   Wrapper de fetch: Bearer token, errores amables, recuperación de 401
│   ├── endpoints.ts Una función por operación del OpenAPI
│   └── session.ts  Persistencia de token/modo en localStorage
├── auth/           AuthContext: sesión invitado/registrado y bootstrap
├── components/     UI compartida (header, dropzone, progreso, pasos, toasts…)
├── hooks/          Hooks de React Query (proyectos, subida, indexación, chat, historial)
├── pages/          Una página por ruta
└── lib/            Utilidades

Rutas

Ruta	Página	Propósito
/	Inicio / Crear	Crear proyecto (nombre + descripción). Lo primero que se ve.
/projects/:id	Proyecto	Subir el .zip, ver el resumen e indexar con progreso.
/projects/:id/chat	Chat	Preguntar a la IA (respuestas con fuentes).
/projects/:id/history	Historial	Conversaciones guardadas (solo registrado).
/projects	Mis proyectos	Listar / borrar proyectos (registrado).
/login, /register	Autenticación	Formularios de acceso.

Notas

• La indexación (POST /projects/{id}/index) es síncrona en el backend: el frontend hace polling de GET /projects/{id}/indexing-status cada ~1,5 s en paralelo para mostrar el progreso, y para de sondear al llegar a completed o failed.
• Los tipos de la API no se escriben a mano: se generan desde el OpenAPI, así que reflejan el contrato compartido con el backend.