Entity

Imported from Xamppy/Entity (AGENTS.md). Install upstream with npx skills add Xamppy/Entity. Copyright stays with the author.

Entity - AI Visibility Audit Platform (GEO/AEO)

Generative Engine Optimization & Answer Engine Optimization Plataforma SaaS multi-tenant para auditar la "AI Readiness" de sitios web.

Project Overview

Entity mide qué tan bien están optimizados los sitios web para motores de búsqueda con IA y comprensión de LLMs. Analiza factores como:

• LLM Readability Score: Qué tan fácil es para un LLM entender el contenido
• AI Readiness Score: Puntuación compuesta de preparación para IA
• Share of AI Voice: Visibilidad estimada en respuestas de IA
• robots.txt Compliance: Compatibilidad con bots de IA (GPTBot, ClaudeBot, etc.)

Tech Stack

Project Structure (Actual — Implemented)

root/
├── AGENTS.md                     # Este archivo — spec del proyecto para agentes IA
├── PROJECT-CONTEXT.md            # Contexto completo del proyecto para LLM handoff
├── package.json                  # Dependencias (npm, no pnpm)
├── tsconfig.json                 # Strict mode + @/* path alias
├── tailwind.config.ts            # Observatory theme tokens + keyframes
├── postcss.config.js             # Tailwind + autoprefixer
├── next.config.ts                # Next.js config
├── docker-compose.yml            # PostgreSQL + app + crawler + Inngest dev
├── Dockerfile.crawler            # Playwright container (1GB RAM, --ipc=host)
├── .env.example                  # Variables de entorno requeridas
├── prisma/
│   └── schema.prisma             # 10 modelos, 6 enums, indexes optimizados
│
└── src/
    ├── app/                              # Next.js App Router
    │   ├── layout.tsx                    # Root layout (dark mode, Instrument Serif)
    │   ├── page.tsx                      # Redirect → /dashboard
    │   ├── globals.css                   # Observatory design system CSS
    │   ├── api/
    │   │   └── inngest/
    │   │       └── route.ts              # Inngest webhook handler
    │   └── (dashboard)/
    │       ├── layout.tsx                # Sidebar + main content shell
    │       ├── page.tsx                  # Redirect → /dashboard
    │       └── dashboard/
    │           ├── page.tsx              # Dashboard home (Server Component)
    │           ├── sites/
    │           │   └── page.tsx          # Sites list (Server Component)
    │           ├── audits/
    │           │   ├── page.tsx          # Audits list (Server Component)
    │           │   └── [id]/
    │           │       └── page.tsx      # Audit detail (Server Component, dynamic)
    │           ├── insights/
    │           │   └── page.tsx          # Insights (Server Component)
    │           └── settings/
    │               └── page.tsx          # Settings ("use client", placeholder)
    │
    ├── components/
    │   ├── ui/                           # shadcn/ui primitives
    │   │   ├── accordion.tsx             # Radix Accordion
    │   │   ├── badge.tsx                 # CVA Badge (6 variants)
    │   │   ├── button.tsx                # CVA Button (6 variants, 5 sizes)
    │   │   ├── progress.tsx              # Radix Progress
    │   │   ├── scroll-area.tsx           # Radix ScrollArea
    │   │   ├── separator.tsx             # Radix Separator
    │   │   └── tooltip.tsx               # Radix Tooltip
    │   │
    │   └── dashboard/                    # Componentes específicos del dashboard
    │       ├── sidebar.tsx               # Collapsible sidebar + mobile drawer
    │       ├── org-switcher.tsx           # Organization dropdown con badges de plan
    │       ├── score-radial.tsx           # Animated SVG radial gauge
    │       ├── trend-chart.tsx            # Recharts AreaChart (score over time)
    │       ├── category-radar.tsx         # Recharts RadarChart (5 categories)
    │       ├── quick-wins.tsx             # Bento grid of quick win cards
    │       ├── activity-feed.tsx          # Recent audit activity list
    │       ├── audit-progress.tsx         # Vertical stepper with Framer Motion
    │       ├── dashboard-view.tsx         # Client view for /dashboard
    │       ├── sites-view.tsx             # Client view for /dashboard/sites
    │       ├── audits-view.tsx            # Client view for /dashboard/audits
    │       ├── insights-view.tsx          # Client view for /dashboard/insights
    │       └── audit-detail-view.tsx      # Client view for /dashboard/audits/[id]
    │
    ├── lib/
    │   ├── db.ts                         # Prisma client singleton
    │   ├── auth.ts                       # Mock session for dev (NextAuth placeholder)
    │   ├── ai.ts                         # Gemini engine (generateObject + Zod schema)
    │   └── utils.ts                      # cn() + safeAction() utility
    │
    ├── inngest/
    │   ├── client.ts                     # Inngest client instance
    │   ├── index.ts                      # Re-exports all functions
    │   └── functions/
    │       ├── audit.crawl.ts            # Step 1: Crawl page with Playwright
    │       ├── audit.analyze.ts          # Step 2: Calculate scores
    │       ├── audit.generate-insights.ts # Step 3: AI insights with Gemini
    │       └── email.weekly-digest.ts    # Cron: Monday 9 AM weekly email
    │
    ├── crawler/
    │   ├── browser.ts                    # Playwright launcher + crawlPage() orchestrator
    │   ├── extractors/
    │   │   ├── robots.ts                 # 7 AI bots compliance check
    │   │   ├── schema.ts                 # Schema.org JSON-LD + Author/ProfilePage
    │   │   ├── content.ts                # Headings, readability, FAQ/HowTo
    │   │   └── performance.ts            # INP measurement (Docker-aware)
    │   └── analyzers/
    │       ├── ai-readiness.ts           # 0-100 composite score (5 categories)
    │       └── llm-readability.ts        # 0-100 LLM parsability score
    │
    ├── actions/                          # Server Actions
    │   ├── site.actions.ts               # CRUD + getSites (soft delete)
    │   ├── audit.actions.ts              # startAudit, getAudit, getRecentAudits, getAuditHistory
    │   └── insight.actions.ts            # getAuditInsights, getQuickWins, getInsightStats
    │
    ├── stores/                           # Zustand stores
    │   ├── ui.store.ts                   # Sidebar state + theme (with persist)
    │   └── org.store.ts                  # Organization switcher state
    │
    ├── emails/                           # React Email templates
    │   ├── weekly-digest.tsx             # Organization-wide stats digest
    │   └── audit-complete.tsx            # Post-audit notification with scores
    │
    └── types/
        └── index.ts                      # Zod schemas + TypeScript types

Architecture Pattern: Server/Client Split

Todas las páginas del dashboard siguen este patrón:

Server Component (page.tsx)              Client Component (*-view.tsx)
┌─────────────────────────┐              ┌──────────────────────────┐
│ - Calls server actions   │    data     │ - "use client"            │
│ - safeAction() fallback  │  ───────►   │ - Framer Motion animations│
│ - Transforms Prisma data │    props    │ - Recharts charts         │
│ - Demo data if no DB     │             │ - Interactive UI          │
└─────────────────────────┘              └──────────────────────────┘

// safeAction() — graceful fallback when DB is unavailable
export async function safeAction<T>(action: () => Promise<T>, fallback: T): Promise<T> {
  try { return await action() } catch { return fallback }
}

Every page has comprehensive demo data hardcoded as a fallback constant. This means the dashboard renders beautifully even without a running database.

Code Standards

TypeScript

• Strict mode ("strict": true)
• Prefiere type sobre interface para consistencia
• Usa Zod para validación en runtime
• NO uses any — usa unknown con type guards

React / Next.js

• Usa Server Components por defecto
• Client Components solo para interactividad ("use client")
• Usa Server Actions para mutaciones
• Patrón Server Component page → Client Component view para TODAS las páginas

Database (Prisma)

• Todas las queries en Server Actions o API routes
• Usa transacciones para operaciones multi-tabla
• Indexa campos frecuentemente consultados
• Usa soft deletes donde sea apropiado (deletedAt en Site)

Inngest Workflows

• Cada step debe ser idempotente
• Usa step.run() para operaciones con retry
• onFailure handlers actualizan el audit status a FAILED
• Los eventos siguen el patrón domain/action.past-tense

Styling — "Observatory" Design System

• Dark cinematic canvas (#09090b) con tokens semánticos
• Colores: canvas (backgrounds), ink (text), emerald (success), amber (warning), rose (danger), iris (AI/accent)
• Fuentes: Instrument Serif (display/headings), Geist (body)
• .ai-glow-border — animated mesh gradient border for AI content
• .ai-glow-border-static — subtle version for secondary AI elements
• .metric-card — dark glass cards with hover effect
• .noise-overlay — film-grain depth texture
• Mobile-first responsive. NO estilos inline.

Naming Conventions

AI Readiness Score Algorithm

El score compuesto (0-100) se calcula así:

AI Bot Compliance

Se verifican 7 bots de IA en robots.txt:

1. GPTBot (OpenAI)
2. OAI-SearchBot (OpenAI Search)
3. ClaudeBot (Anthropic)
4. Anthropic-AI (Anthropic)
5. Google-Extended (Google AI)
6. PerplexityBot (Perplexity)
7. Applebot-Extended (Apple Intelligence)

Key Technical Discoveries

Cosas que ya se resolvieron y NO deben re-introducirse:

1. @radix-ui/react-badge NO EXISTE — Badge es pure Tailwind via CVA
2. Ruta (dashboard) no añade URL segment — Las páginas están en (dashboard)/dashboard/ para que los URLs sean /dashboard/*
3. Vercel AI SDK: Usar generateObject() para output estructurado, NO generateText() con Output.object
4. Inngest client: No usar schemas: new Map() — causa type errors
5. Inngest onFailure: Cast event.data via Record<string, unknown> para acceder a campos
6. Prisma enums vs Zod: InsightCategory enum usa snake_case (llm_readability), Zod usa kebab-case — hay un categoryMap en audit.generate-insights.ts
7. PerformanceEventTiming: TypeScript no tiene interactionId/durationThreshold — hay declare global augmentations en performance.ts
8. React Email <Preview>: Números deben ser wrapped con String() por constraint ReactNode & string
9. Prisma JSON fields: Record<string, unknown>[] no es assignable a InputJsonValue — usar JSON.parse(JSON.stringify(...))
10. INP en Docker: Necesita ≥1GB RAM, --ipc=host, múltiples muestras con P75 + detección de varianza
11. autoprefixer: Necesario para PostCSS — instalado como devDependency
12. AuditActivity.status: El tipo del activity feed debe incluir GENERATING_INSIGHTS además de los otros 5 status

Build Info

Route (app)                                 Size  First Load JS
┌ ○ /                                      140 B         101 kB
├ ○ /_not-found                            986 B         102 kB
├ ƒ /api/inngest                           140 B         101 kB
├ ○ /dashboard                            116 kB         268 kB
├ ○ /dashboard/audits                    2.69 kB         154 kB
├ ƒ /dashboard/audits/[id]               9.05 kB         167 kB
├ ○ /dashboard/insights                  2.84 kB         155 kB
├ ○ /dashboard/settings                  4.76 kB         154 kB
└ ○ /dashboard/sites                     4.09 kB         156 kB

○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

• npx tsc --noEmit → 0 errors
• npm run build → exitoso, 10 rutas

Development Commands

# Desarrollo
npm run dev               # Next.js dev server (Turbopack)
npm run build             # Build de producción
npm run start             # Iniciar servidor de producción
npm run typecheck         # npx tsc --noEmit

# Base de datos
npm run db:push           # Push schema a DB (desarrollo)
npm run db:migrate        # Crear migración
npm run db:studio         # Abrir Prisma Studio
npm run db:seed           # Ejecutar seeds (tsx prisma/seed.ts)

# Inngest
npm run inngest:dev       # Iniciar servidor de desarrollo de Inngest

# Testing (no hay tests escritos aún)
npm test                  # Vitest
npm run test:unit         # Vitest run
npm run test:e2e          # Playwright test
npm run test:coverage     # Vitest + coverage

Environment Variables

Ver .env.example para todas las variables necesarias.

Variables críticas:

• DATABASE_URL — Conexión a PostgreSQL
• INNGEST_SIGNING_KEY — Clave de Inngest
• INNGEST_EVENT_KEY — Event key de Inngest
• GEMINI_API_KEY — API key de Google AI Studio
• RESEND_API_KEY — API key de Resend
• AUTH_SECRET — Para NextAuth.js (cuando se implemente)

What's NOT Done Yet

1. Autenticación real — auth.ts es un mock que devuelve sesión hardcoded. NextAuth.js no está configurado. No existen páginas de login/register.
2. Tests — Vitest y Playwright están en scripts pero no hay archivos de test.
3. Settings page — Renderiza un placeholder estático.
4. Dockerfile del app — Solo existe Dockerfile.crawler, falta el principal para Next.js.
5. Score breakdown real — El dashboard usa datos demo para breakdown y radar cuando hay datos reales (falta calcular desde PageAudit).
6. Suspense boundaries — No hay loading states ni error boundaries en las páginas.
7. Empty states — Las vistas no tienen diseño para "sin datos" (siempre hay demo data como fallback).

Git Workflow

1. Crear branch desde main: git checkout -b feature/nombre
2. Commits con conventional commits: feat:, fix:, docs:, refactor:
3. Push y crear PR
4. Review y merge a main

# Ejemplos de commits
git commit -m "feat(crawler): add robots.txt parser for AI bots"
git commit -m "fix(dashboard): correct score calculation rounding"
git commit -m "refactor(inngest): split audit workflow into steps"