Skip to content

Base de datos y modelo de dominio

Por que la base de datos es una pieza central

Para nosotros, la base de datos no esta solo para guardar formularios. En SEO Growth Engine guarda la informacion operativa del proyecto: sitios, usuarios, permisos, ejecuciones, prompts, resultados, errores, artefactos e historial quedan persistidos para que el trabajo SEO sea trazable.

Cada analisis que lanzamos queda registrado como un run con estado, fechas, logs, ficheros generados y resultados reutilizables.

Diagrama del modelo

User Django auth id, username, email SiteAccess user_id + site_id permisos por cliente Site activo SEO url, crawl, GSC, GA4, IA AnalysisRun site_id + triggered_by estado, progreso, report AIVisibilityPrompt site_id categoria, prompt, keywords AIVisibilityRun site_id + triggered_by provider, payload, logs AIVisibility Observation run_id + prompt_id menciones y citas 1:N N:1 Site 1:N AnalysisRun Site 1:N Prompt Site 1:N AI Run Prompt + Run generan Observation
UserDjango auth
  • PK id
  • username
  • email
  • is_staff
  • is_superuser
SiteAccessPermisos por cliente
  • PK id
  • FK user_id -> User
  • FK site_id -> Site
  • can_run_analysis
  • can_manage_ai_visibility
SiteActivo SEO
  • PK id
  • name, slug, base_url
  • competitor_url, brand_terms
  • max_pages, crawl_delay
  • gsc_property, ga4_property_id
AnalysisRunEjecucion tecnica
  • PK id
  • FK site_id -> Site
  • FK triggered_by_id -> User
  • status, progress_percent
  • include_crawl, include_gsc, include_ga4
  • output_dir, report_path, artifacts
AIVisibilityPromptPrompt configurable
  • PK id
  • FK site_id -> Site
  • name, category
  • prompt_text
  • target_keywords
  • is_active
AIVisibilityRunEjecucion de IA
  • PK id
  • FK site_id -> Site
  • FK triggered_by_id -> User
  • provider, status
  • result_payload
  • log_output
AIVisibilityObservationResultado por prompt
  • PK id
  • FK run_id -> AIVisibilityRun
  • FK prompt_id -> AIVisibilityPrompt
  • brand_mentioned, domain_cited, cited_url
  • competitor_name, ranking_position, response_excerpt
User 1:N SiteAccess Site 1:N SiteAccess Site 1:N AnalysisRun Site 1:N AIVisibilityPrompt Site 1:N AIVisibilityRun AIVisibilityRun 1:N AIVisibilityObservation AIVisibilityPrompt 1:N AIVisibilityObservation

Tablas principales

Modelo Responsabilidad Por que importa
Site Representa cada web o cliente gestionado por la plataforma Es el centro del sistema: URL, marca, competidor, limites de crawl e integraciones
SiteAccess Une usuarios con sitios concretos Permite que un cliente vea solo su proyecto y no todos los clientes
AnalysisRun Guarda cada ejecucion tecnica Da trazabilidad: estado, progreso, fechas, errores, artefactos y modulo ejecutado
AIVisibilityPrompt Define los prompts de visibilidad IA por sitio Hace configurable la capa de IA sin tocar codigo
AIVisibilityRun Registra ejecuciones independientes de visibilidad IA Permite medir IA como proceso propio, no solo como parte del informe tecnico
AIVisibilityObservation Persiste resultados por prompt Guarda menciones, citas de dominio, competidores y posicion estimada

Relaciones importantes

  • Un User puede tener acceso a varios Site mediante SiteAccess.
  • Un Site puede tener muchos AnalysisRun, lo que crea historico de trabajo.
  • Un Site puede tener muchos AIVisibilityPrompt activos o inactivos.
  • Un AIVisibilityRun agrupa resultados de prompts y genera AIVisibilityObservation.
  • Un AnalysisRun tambien puede incluir IA dentro del informe final si el usuario marca ese modulo.

Campos que demuestran trazabilidad

En AnalysisRun hemos incluido campos que demuestran que no es una demo plana:

  • status, progress_percent, current_step y status_message permiten seguimiento en vivo.
  • cancel_requested, cancelled_at y retry_of hacen que cancelar o reintentar sea parte del dominio.
  • options_snapshot conserva que modulos se lanzaron aunque la configuracion del sitio cambie despues.
  • artifacts, output_dir y report_path conectan la base de datos con los ficheros generados.
  • log_output conserva el rastro tecnico de lo que paso durante el run.

Decisiones de diseno

  • Usamos el ORM de Django para trabajar con relaciones reales y no con SQL disperso.
  • Separamos Site de SiteAccess para poder tener permisos por cliente.
  • Separamos AnalysisRun de AIVisibilityRun porque una ejecucion tecnica y una ejecucion IA tienen ciclos de vida distintos.
  • Guardamos resultados estructurados en campos JSONField cuando el contenido puede crecer o cambiar, como artefactos, payloads y snapshots.
  • Mantenemos fechas y estados para poder explicar historico, trazabilidad, cancelacion y reintentos.

Funcion dentro del proyecto

Nuestra base de datos sostiene la parte persistente del proyecto. Sin este modelo solo tendriamos una herramienta que lanza scripts. Con este modelo tenemos usuarios, clientes, permisos, procesos, resultados, historial y evidencias guardadas.