Saltar a contenido

Guía del Repositorio para Agentes AI

Este documento está pensado para asistentes AI (Copilot, Claude, GPT, etc.) que necesiten entender rápido el proyecto y hacer cambios seguros.

1. Mapa rápido del sistema

Aeternus es un proyecto full-stack con dos runtimes principales:

  • Frontend web en Next.js (App Router) dentro de src/
  • Backend core en FastAPI dentro de core/

Flujo general:

  1. El usuario interactúa en la UI (src/app + src/components)
  2. La UI llama API routes de Next (src/app/api/*) y/o endpoints del core (core/app/routes/*)
  3. Persistencia principal vía Prisma/PostgreSQL y algunas capacidades sobre Neo4j
  4. Integraciones externas: Auth0, OpenAI y ElevenLabs

2. Estructura clave que un agente debe conocer

  • src/app/: rutas de Next.js (páginas + API routes)
  • src/components/: componentes React por feature (chat, admin, landing, etc.)
  • src/hook/: hooks custom
  • src/lib/: integraciones y clientes (Prisma, Neo4j, tools)
  • src/utils/: utilidades de apoyo y helpers
  • src/config/: configuración de acceso y comportamiento
  • core/app/main.py: inicialización FastAPI
  • core/app/routes/: endpoints del backend core
  • core/app/schemas.py: modelos de validación backend
  • prisma/schema.prisma: modelo de datos SQL
  • scripts/: automatizaciones Docker/AWS/acceso

3. Comandos operativos de referencia

Frontend (root):

npm run dev
npm run dev:clean
npm run lint
npm run build

Backend core:

cd core
make setup
make run
make check
make run-prod

Atajos desde root:

make core-setup
make core-run
make core-stop
make docker-core-up
make docker-core-down

4. Convenciones prácticas para cambios seguros

  • Haz cambios mínimos y localizados; evita refactors masivos sin necesidad.
  • Respeta la separación por capas:
  • UI en src/components
  • routing/páginas en src/app
  • utilidades puras en src/utils
  • integraciones en src/lib
  • En backend, agrega endpoints por dominio en archivos de core/app/routes.
  • Evita any en TypeScript cuando sea posible.
  • Para cambios de datos, modifica prisma/schema.prisma y genera migración.
  • Si tocas APIs, valida impacto en frontend y en core.

5. Rutas y zonas sensibles

  • Autenticación y sesión: src/app/api/auth, componentes de auth, Auth0 env vars.
  • Chat y persistencia: src/app/api/chat, core/app/routes/chat.py, core/app/routes/chat_storage.py.
  • Admin y permisos: src/app/admin, src/config/admin-access.ts, src/utils/access-manager.ts.
  • TTS y providers externos: src/app/api/tts, core/app/routes/tts.py.
  • Estado y salud de servicios: core/app/routes/health.py, core/app/routes/status.py.

6. Checklist para un agente antes de proponer cambios

  1. Identificar si el cambio es frontend, backend o full-stack.
  2. Buscar archivos equivalentes existentes antes de crear nuevos.
  3. Verificar comandos de validación mínimos:
  4. Frontend: npm run lint
  5. Backend: cd core && make check
  6. Confirmar variables de entorno implicadas.
  7. Revisar riesgo de regresión en rutas API y contratos de datos.

7. Guía de diagnóstico rápido

  • Si falla frontend build/lint, revisar imports, tipos y rutas en src/app/api.
  • Si falla backend, correr cd core && make check para errores de sintaxis.
  • Si chat responde vacío/inestable:
  • verificar OPENAI_API_KEY o CORE_MOCK_MODE
  • revisar URL de core (NEXT_PUBLIC_CORE_API_BASE_URL)
  • Si falla persistencia:
  • validar DATABASE_URL
  • revisar Prisma client y modelo en prisma/schema.prisma

8. Variables de entorno importantes (alto impacto)

  • Frontend: .env.local
  • Backend core: core/.env

Ejemplos frecuentes:

  • NEXT_PUBLIC_CORE_API_BASE_URL
  • OPENAI_API_KEY
  • CORE_MOCK_MODE
  • DATABASE_URL
  • AUTH0_*
  • ELEVENLABS_*

Para detalle completo, consultar docs/environment-variables.md.

9. Estrategia recomendada para agentes AI

  1. Explorar primero: mapear archivos relacionados y contratos actuales.
  2. Cambiar después: una modificación coherente por vez.
  3. Validar al final: lint/check según capa tocada.
  4. Documentar impacto: qué cambió, por qué, y posibles riesgos.

10. Qué no hacer (anti-patrones)

  • No introducir nuevas abstracciones si el repo ya tiene patrón establecido.
  • No mover carpetas o renombrar módulos ampliamente sin necesidad explícita.
  • No asumir que una API route de Next y un endpoint de FastAPI son equivalentes; verificar uso real.
  • No editar variables de entorno en código hardcodeando secretos.

11. Referencias útiles dentro del repo

  • README.md
  • docs/setup-local.md
  • docs/project-structure.md
  • docs/common-tasks.md
  • docs/contributing.md
  • core/README.md

Última actualización: 2026-03-21