Documentación del proyecto¶

1. Introducción¶

SEO Growth Engine es nuestra aplicación web para centralizar análisis SEO técnico, datos de visibilidad orgánica y generación de informes para proyectos web. Con este sistema podemos registrar sitios, asignarlos a usuarios internos o clientes, ejecutar análisis bajo demanda y conservar un histórico de ejecuciones con sus artefactos asociados.

El objetivo principal del proyecto es centralizar en un mismo entorno varias capas de trabajo SEO:

• rastreo técnico del sitio web;
• análisis de incidencias y estructura interna;
• integración opcional con Google Search Console y Google Analytics 4;
• medición de visibilidad en asistentes de IA mediante prompts;
• generación de informes HTML listos para revisión o entrega.

El problema que resuelve es la fragmentación habitual del trabajo SEO. En lugar de usar herramientas separadas para crawling, datos de búsqueda, analítica, seguimiento de prompts y reporting, el proyecto unifica estos procesos en una sola plataforma con control de acceso por usuario.

2. Descripción general¶

El sistema está construido principalmente con Django y se organiza como una aplicación web con autenticación por sesión. Tiene una portada pública, una zona privada para usuarios autenticados y un motor de análisis SEO escrito en Python.

A alto nivel, el funcionamiento es el siguiente:

1. Un usuario interno configura uno o varios sitios en el sistema.
2. El sistema guarda datos del sitio, parámetros de rastreo y credenciales opcionales para GSC y GA4.
3. Un usuario con permisos puede lanzar una ejecución de análisis.
4. La ejecución se procesa en segundo plano, ya sea mediante threading local o mediante Redis + RQ.
5. El motor genera artefactos en disco (CSV, JSON, HTML) dentro de la carpeta output/.
6. El dashboard permite revisar el estado, cancelar o reintentar ejecuciones y abrir el informe final.

Tecnologías y capacidades detectadas en el repositorio:

• Backend web con Django.
• Frontend server-rendered con plantillas Django.
• Frontend adicional en Vue 3 + TypeScript + Vite, integrado de forma progresiva.
• Base de datos mediante ORM de Django, con SQLite por defecto y soporte para PostgreSQL.
• API JSON interna propia bajo /api/.
• Autenticación basada en usuarios y sesiones de Django.
• Panel de administración real mediante Django Admin.
• Cola de tareas opcional con Redis + RQ.
• Integraciones externas con Google Search Console, Google Analytics 4, OpenAI y correo SMTP.
• Generación de informes HTML a partir de Jinja2.

No se han detectado en el repositorio archivos de Docker, docker-compose, configuración de Nginx ni una API pública construida con Django REST Framework.

3. Tecnologías utilizadas¶

Las siguientes tecnologías aparecen realmente en el código fuente o en los archivos de dependencias del proyecto.

4. Estructura del proyecto¶

4.1 Vista general simplificada¶

seo-growth-engine/
|-- dashboard/
|   |-- api/
|   |-- management/commands/
|   |-- migrations/
|   |-- shared/
|   |-- static/
|   |-- tasks/
|   |-- templates/web/
|   `-- web/
|-- docs/
|-- engine/
|-- frontend/
|   |-- src/
|   `-- static/vue/
|-- ftp-export/
|-- main/
|-- shared/
|-- static/
|-- templates/
|-- manage.py
|-- seo_engine.py
|-- requirements.txt
|-- Procfile
`-- gunicorn.conf.py

4.2 Carpetas y archivos principales¶

• main/: configuración global del proyecto Django (settings.py, urls.py, wsgi.py, asgi.py).
• dashboard/: aplicación principal de negocio. Contiene modelos, vistas web, API interna, formularios, tareas en segundo plano, comandos de administración y plantillas privadas.
• engine/: motor SEO independiente del dashboard. Implementa el crawler, auditorías, integraciones con GSC y GA4, AI Visibility y generación de reportes.
• frontend/: cliente Vue 3 con TypeScript y Vite. Su build se publica en frontend/static/vue/ para que Django la sirva.
• shared/: recursos compartidos entre vistas, como plantilla base, estilos generales y assets comunes.
• templates/: plantillas globales. Destaca report.html, usada por el motor para renderizar el informe final.
• static/: recursos estáticos adicionales del proyecto.
• ftp-export/: exportación estática de la home pública y de la página "How it works", preparada para alojamientos basados solo en FTP.
• docs/: documentación auxiliar ya existente en el repositorio.
• manage.py: punto de entrada estándar para comandos Django.
• seo_engine.py: CLI propia para ejecutar el motor SEO fuera del flujo web.
• requirements.txt: dependencias Python del proyecto.
• Procfile: define un proceso web y un proceso worker para despliegues tipo PaaS.
• gunicorn.conf.py: configuración del servidor Gunicorn.

5. Arquitectura del sistema¶

La arquitectura del proyecto combina una aplicación web de gestión con un motor de análisis que genera artefactos persistentes en disco.

5.1 Capas principales¶

• Capa pública: portada principal y página explicativa servidas con plantillas Django.
• Capa privada: dashboard autenticado para usuarios internos y clientes.
• Capa de API interna: endpoints JSON consumidos por el frontend Vue.
• Capa de ejecución en segundo plano: procesamiento de runs de análisis y runs de AI Visibility.
• Capa de generación de artefactos: exportación de resultados a HTML, JSON y CSV.

5.2 Flujo general de una ejecución¶

1. El usuario inicia sesión.
2. Accede a uno de los sitios a los que tiene permiso.
3. Selecciona los módulos a ejecutar:
4. rastreo técnico;
5. Search Console;
6. GA4;
7. AI Visibility.
8. Se crea un registro AnalysisRun o AIVisibilityRun en base de datos.
9. El sistema lanza el trabajo en segundo plano.
10. El motor ejecuta las fases del análisis y va actualizando el progreso.
11. Se generan artefactos dentro de output/<host>-<timestamp>/.
12. El dashboard permite revisar el estado, ver logs, descargar archivos y abrir el informe HTML.

5.3 Observación importante¶

El proyecto no es únicamente un frontend. La parte esencial está en la lógica backend y en el motor de análisis, mientras que la interfaz web funciona como capa de administración, disparo de procesos y visualización de resultados.

6. Backend y lógica de negocio¶

6.1 Configuración global de Django¶

La configuración principal se encuentra en main/settings.py. Los aspectos más relevantes detectados son:

• carga automática de un archivo .env si existe;
• activación de SQLite por defecto;
• soporte para PostgreSQL mediante DATABASE_URL;
• servicio de estáticos con WhiteNoise;
• idioma por defecto es-es;
• zona horaria configurable mediante DJANGO_TIME_ZONE;
• endurecimiento de cookies y cabeceras según variables de entorno;
• soporte para colas RQ o fallback local en hilo.

6.2 Aplicación dashboard¶

Es la aplicación central del negocio. Desde aquí se controla casi toda la funcionalidad web:

• registro y edición de sitios;
• alta y gestión de clientes;
• control de accesos por sitio;
• lanzamiento, seguimiento, cancelación y reintento de análisis;
• gestión de prompts de AI Visibility;
• vistas HTML clásicas;
• endpoints JSON para el frontend Vue;
• integración con correo y notificaciones.

6.3 Autenticación y permisos¶

El proyecto usa el sistema estándar de usuarios de Django (django.contrib.auth). No se detecta un modelo de usuario personalizado.

El control de acceso funciona así:

• los usuarios is_staff o is_superuser tienen acceso global;
• los clientes normales acceden solo a los sitios asignados;
• la relación entre usuarios y sitios se controla con el modelo SiteAccess;
• existen permisos separados para:
• ejecutar análisis;
• gestionar prompts de AI Visibility.

Las vistas de autenticación emplean:

• login;
• logout;
• cambio de contraseña;
• redirección al dashboard privado tras iniciar sesión.

6.4 API interna¶

La API está en dashboard/api/views.py y se expone bajo /api/. No usa Django REST Framework; las respuestas se construyen con JsonResponse.

Endpoints detectados:

• GET /api/bootstrap/
• GET /api/dashboard/
• GET /api/session/
• POST /api/session/login/
• POST /api/session/logout/
• GET /api/sites/
• GET /api/runs/
• GET /api/runs/<id>/

Esta API se usa principalmente para el cliente Vue.

6.5 Panel de administración¶

El proyecto incluye un panel real de Django Admin con personalización de cabeceras y registros para:

• Site
• SiteAccess
• AnalysisRun
• AIVisibilityPrompt
• AIVisibilityRun
• AIVisibilityObservation

La URL del admin es configurable mediante DJANGO_ADMIN_URL, lo que mejora la seguridad en producción.

7. Base de datos y modelo de datos¶

7.1 Motor de base de datos¶

Se detectan dos modos de funcionamiento:

• SQLite para desarrollo local, usando db.sqlite3.
• PostgreSQL en entornos donde se configure DATABASE_URL.

7.2 Modelos principales¶

Site¶

Representa un sitio web gestionado por la plataforma. Guarda, entre otros, estos datos:

• nombre;
• slug;
• URL base;
• URL de competidor;
• términos de marca;
• límites de rastreo;
• parámetros de spellcheck;
• configuración de GSC;
• configuración de GA4;
• estado activo/inactivo.

SiteAccess¶

Relaciona un usuario con un sitio y define permisos concretos:

• acceso al sitio;
• permiso para ejecutar análisis;
• permiso para gestionar AI Visibility.

AnalysisRun¶

Representa una ejecución completa del análisis SEO. Guarda:

• sitio asociado;
• usuario que lanzó el proceso;
• estado;
• módulos activados;
• porcentaje de progreso;
• mensajes de estado;
• rango de fechas;
• carpeta de salida;
• ruta del informe;
• artefactos generados;
• logs;
• referencia a una posible reejecución (retry_of).

AIVisibilityPrompt¶

Define un prompt reutilizable por sitio para evaluar visibilidad en asistentes de IA. Incluye:

• nombre;
• categoría;
• texto del prompt;
• keywords objetivo;
• estado activo/inactivo.

AIVisibilityRun¶

Representa una ejecución específica del módulo de AI Visibility. Guarda:

• proveedor;
• estado;
• notas;
• payload de resultados;
• logs;
• relación con una ejecución anterior si es un reintento.

AIVisibilityObservation¶

Guarda observaciones concretas extraídas de una ejecución de AI Visibility, como:

• asistente analizado;
• nombre mencionado;
• si la marca fue citada;
• si el dominio apareció citado;
• competidor detectado;
• posición estimada;
• fragmento de respuesta;
• notas.

7.3 Relaciones principales¶

• Un Site tiene muchos AnalysisRun.
• Un Site tiene muchos AIVisibilityPrompt.
• Un Site tiene muchos AIVisibilityRun.
• Un AIVisibilityRun tiene muchas AIVisibilityObservation.
• Un User se relaciona con muchos Site a través de SiteAccess.
• AnalysisRun y AIVisibilityRun pueden apuntar a una ejecución previa mediante retry_of.

8. Motor de análisis SEO¶

La carpeta engine/ contiene el núcleo técnico del proyecto.

8.1 Módulos principales del motor¶

• crawler.py: realiza el rastreo asíncrono del sitio, detecta HTML frente a assets y extrae enlaces internos.
• analysis.py: calcula incidencias SEO, grafo interno, huérfanas, canonicals, redirecciones y estructura de URL.
• gsc.py: consulta Google Search Console y construye bloques de keywords, quick wins, CTR leaks, canibalización y comparativas.
• ga4.py: consulta Google Analytics 4 y resume sesiones, usuarios, conversiones, landing pages y señales de tráfico procedente de asistentes de IA.
• ai_visibility.py: ejecuta prompts mediante OpenAI, interpreta menciones, cita dominios y calcula una puntuación de visibilidad.
• spellcheck.py: corrección ortográfica opcional con LanguageTool.
• report_data.py: consolida toda la información en una estructura común.
• report.py: guarda data.json y renderiza report.html con Jinja2.
• runner.py: orquesta el pipeline completo.

8.2 Resultados generados¶

Cada ejecución crea una carpeta en output/ con un identificador tipo:

output/<host>-YYYYMMDD-HHMMSS>/

Los artefactos detectados en el código incluyen, entre otros:

• report.html
• data.json
• pages.csv
• assets.csv
• issues.csv
• orphans.csv
• redirects.csv
• redirect_chains.csv
• canonical_issues.csv
• url_structure.csv
• spelling.csv
• gsc_rows.csv
• gsc_top_keywords.csv
• gsc_quick_wins.csv
• gsc_ctr_leaks.csv
• gsc_cannibalization.csv
• gsc_winners_pages.csv
• gsc_losers_pages.csv
• gsc_content_expansion.csv
• ga4_landing_pages.csv
• ga4_source_medium.csv
• ga4_ai_referrals.csv
• action_plan.csv
• ai_visibility.json

8.3 Informe HTML final¶

El informe técnico principal se renderiza desde templates/report.html. Según el código del template, el informe puede incluir secciones como:

• Overview
• Keyword Intelligence
• Keywords
• Pages
• Technical
• AI Visibility
• Before / After

Además, el sistema compara automáticamente una ejecución con la anterior si encuentra un data.json previo válido en la carpeta output/.

9. Frontend y capa de presentación¶

9.1 Frontend principal del proyecto¶

El frontend principal en producción es el renderizado clásico de Django. Las vistas HTML se encuentran sobre todo en:

• dashboard/templates/web/
• shared/templates/web/

Se detectan páginas para:

• home pública;
• explicación del producto;
• login;
• dashboard;
• lista de clientes;
• detalle de sitio;
• detalle de ejecución;
• gestión de AI Visibility;
• cambio de contraseña.

9.2 Frontend Vue integrado¶

El repositorio incluye un frontend adicional en frontend/ con:

• Vue 3
• TypeScript
• Pinia
• Vue Router
• Vite

Rutas Vue detectadas:

• /login
• /app/
• /app/runs/:id/

La integración con Django es progresiva:

• se puede activar con ?ui=vue;
• también puede activarse mediante variables de entorno;
• si no existe el build de Vite, Django hace fallback a las plantillas clásicas.

9.3 Build del frontend¶

vite.config.ts define que el build se publique en:

frontend/static/vue/

Esto permite que Django sirva los assets generados por Vite como parte de sus estáticos.

9.4 Cliente estático en ftp-export¶

La carpeta ftp-export/ contiene una exportación HTML/CSS de la home pública y de la página informativa. Es útil para publicar una versión estática de presentación, pero no sustituye la aplicación completa, ya que:

• no ofrece autenticación;
• no ejecuta análisis;
• no tiene base de datos;
• no reemplaza al backend Django.

10. Servicios externos e integraciones¶

10.1 Google Search Console¶

El proyecto puede conectarse a Search Console para enriquecer los informes con:

• consultas;
• páginas;
• clics;
• impresiones;
• CTR;
• posición media;
• comparativas entre periodos.

La integración usa service accounts y requiere propiedad y JSON de credenciales.

10.2 Google Analytics 4¶

El sistema puede consultar GA4 para obtener:

• sesiones;
• usuarios;
• page views;
• conversiones;
• landing pages;
• source / medium;
• señales de tráfico relacionadas con asistentes de IA.

10.3 OpenAI¶

El módulo AI Visibility usa la librería de OpenAI para:

• lanzar prompts definidos por sitio;
• utilizar búsqueda web;
• identificar menciones de marca;
• detectar citas de dominio;
• evaluar competidores;
• calcular una puntuación de visibilidad.

10.4 Correo SMTP¶

El sistema envía notificaciones por correo cuando una ejecución:

• finaliza correctamente;
• falla.

Los destinatarios se definen mediante configuración y pueden incluir tanto al usuario lanzador como a una lista operativa.

10.5 Redis + RQ¶

Cuando se configura REDIS_URL y el backend de colas adecuado, los trabajos pasan a ejecutarse mediante:

• colas RQ;
• workers separados;
• procesos de larga duración fuera del hilo principal web.

Si Redis no está disponible, el proyecto hace fallback a un hilo daemon local.

11. Variables de entorno¶

El repositorio contiene un .env.example y además main/settings.py, engine/ y el frontend referencian variables adicionales. A continuación se resumen las más relevantes.

11.1 Variables principales de Django¶

11.2 Base de datos y colas¶

11.3 Seguridad y sesión¶

11.4 Correo y notificaciones¶

11.5 Integraciones externas¶

11.6 Frontend y despliegue¶

12. Scripts y comandos de ejecución¶

12.1 Puesta en marcha básica de Django¶

pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

12.2 Comandos de administración propios¶

python manage.py bootstrap_dashboard --username boss --email boss@example.com
python manage.py bootstrap_client_user --site-slug mi-sitio --username cliente1 --password clave123
python manage.py runworker

Descripción:

• bootstrap_dashboard: crea o actualiza el usuario interno inicial, el sitio base y prompts de ejemplo.
• bootstrap_client_user: crea o actualiza un usuario cliente y le asigna un sitio.
• runworker: levanta el worker de RQ para colas Redis.

12.3 Ejecución del motor SEO por línea de comandos¶

python seo_engine.py full --site https://example.com
python seo_engine.py full --site https://example.com --competitor https://competidor.com --use-gsc --use-ga4

La CLI permite ejecutar el motor sin pasar por la interfaz web.

12.4 Frontend Vue¶

cd frontend
npm install
npm run dev
npm run build

El comando build publica los assets en frontend/static/vue/.

12.5 Despliegue de estáticos¶

python manage.py collectstatic --noinput
gunicorn main.wsgi:application --config gunicorn.conf.py

13. Despliegue y operación¶

13.1 Procesos detectados¶

El archivo Procfile define dos procesos:

• web: gunicorn main.wsgi:application --config gunicorn.conf.py
• worker: python manage.py runworker

Esto indica que el proyecto está preparado para despliegues donde el proceso web y el proceso de tareas se separan.

13.2 Estrategia de estáticos¶

Los estáticos se sirven con WhiteNoise. Además, el frontend Vue deja su build dentro del árbol de estáticos para que Django lo pueda exponer sin infraestructura adicional.

13.3 Estrategia de colas¶

El sistema soporta dos modos:

• Modo simple/local: hilos daemon internos.
• Modo recomendado para producción: Redis + RQ + worker independiente.

13.4 Observaciones de infraestructura¶

Sí se detecta:

• configuración para Gunicorn;
• Procfile;
• soporte para PostgreSQL;
• soporte para Redis;
• checklist de producción en docs/production-checklist.md.

No se detecta:

• Dockerfile;
• docker-compose.yml;
• configuración de Nginx;
• pipeline CI/CD en el repositorio.

14. Pruebas y estado del repositorio¶

14.1 Pruebas automáticas localizadas¶

Se han localizado al menos estos archivos de pruebas:

• dashboard/tests/test_dashboard.py
• dashboard/tests/test_crawler.py

Por su contenido, cubren principalmente:

• autenticación y vistas;
• API interna;
• permisos y accesos por sitio;
• creación, cancelación y reintento de runs;
• notificaciones por correo;
• persistencia de resultados de AI Visibility;
• generación de informes;
• comportamiento del crawler asíncrono;
• integración con colas y fallback local.

En dashboard/tests/test_dashboard.py se han identificado 66 funciones de prueba y en dashboard/tests/test_crawler.py una prueba adicional de concurrencia del crawler.

14.2 Validación durante esta revisión¶

Durante esta revisión documental se intentó ejecutar:

python manage.py check

En el entorno actual no fue posible completarlo porque la sesión no dispone de Django instalado en el intérprete activo. Por tanto, la documentación se ha elaborado a partir del análisis del repositorio y no de una ejecución funcional completa del proyecto.

15. Valoración técnica del proyecto¶

Desde un punto de vista técnico, hemos construido una estructura sólida y bastante completa para un entorno académico o preproductivo:

• separa claramente configuración, lógica de negocio, motor de análisis y frontend;
• utiliza modelos de datos coherentes con el dominio del problema;
• contempla autenticación, permisos y administración;
• ofrece soporte tanto para operación local como para despliegues más serios con PostgreSQL y Redis;
• genera artefactos reutilizables y un informe HTML bien estructurado;
• incorpora una capa Vue moderna sin romper el funcionamiento clásico de Django.

Las principales áreas de mejora detectadas son de infraestructura más que de lógica de negocio:

• falta de contenedorización;
• ausencia de pipeline CI/CD visible;
• dependencia del entorno para ejecutar y validar fácilmente la aplicación;
• necesidad de configurar servicios externos reales para activar toda la funcionalidad.

16. Conclusión¶

SEO Growth Engine es una plataforma web para gestión y ejecución de análisis SEO con orientación clara a trabajo operativo y entrega de informes. El repositorio muestra una combinación de backend robusto en Django, motor de análisis especializado en Python, integración opcional con datos externos y una capa de frontend moderna en Vue.

En conjunto, el proyecto no se limita a ser una página web, sino que constituye una aplicación completa con:

• autenticación;
• control de accesos;
• persistencia de datos;
• procesos en segundo plano;
• integraciones externas;
• reporting automático;
• soporte para usuarios internos y clientes.

Por su arquitectura y alcance, puede considerarse un proyecto técnico de complejidad media-alta, adecuado para ser presentado como desarrollo formal en un contexto educativo.