ApisDom Studio: Plataforma SaaS con Next.js 16, FastAPI y Claude Sonnet

Pipeline de generacion de contenido

Una llamada a POST /v1/generate lanza un flujo secuencial de 8 pasos que parte del brief del usuario y termina con un JSON completo persistido en historial. El frontend actua como proxy firmado hacia el backend FastAPI para que la clave del backend no toque nunca el navegador.

Streaming SSE en tiempo real

Cuando el request trae stream: true, el backend devuelve StreamingResponse con text/event-stream y el frontend consume con EventSource. Cada evento lleva tipo y payload:

El handler esta en streaming.py y el usuario ve el contenido aparecer progresivamente sin esperar a que Claude termine.

Pipeline de adaptacion a redes sociales (POST /v1/adapt)

Una vez generado un contenido, el usuario puede adaptarlo a 7 plataformas sociales sin coste extra para adaptaciones de 1 a 3 plataformas (1 credito) o 4 a 7 plataformas (2 creditos), definido en credit-costs.ts.

Las adaptaciones no consumen web_search y no generan nuevas citations — trabajan sobre el contenido ya existente.

Perfiles de generacion reutilizables

Los usuarios (y el panel admin) pueden guardar profiles con configuracion preferida de tono, longitud, audiencia, idioma, style_guide, brand_voice y preferencias SEO. Cada request puede referenciar un perfil por profile_id y el backend los mergea con los parametros del request antes de construir el prompt. Endpoints en routes_profiles.py y UI en app/[locale]/profiles/.

Cada generacion queda registrada en el historial del usuario con todos los parametros, tokens consumidos, fuentes citadas y el JSON completo del resultado. El historial se expone en app/[locale]/history/ con filtros, re-descarga y re-uso como plantilla.

Editor TipTap y panel de administracion

APISDOM Studio tiene dos piezas de UI centrales: el editor WYSIWYG con TipTap donde el usuario ve y retoca el contenido generado por Claude, y un panel de administracion completo donde se gestionan usuarios, creditos, modelos, blog, partners y metricas globales.

Editor WYSIWYG — TipTap 3.20

El editor usa TipTap 3.20 con un conjunto completo de extensiones oficiales instaladas en produccion: StarterKit, Image, Link, Placeholder, Table + TableCell / TableHeader / TableRow, TextAlign y CodeBlockLowlight con resaltado de sintaxis via lowlight 3.3. Implementacion en editor/:

• EditorContentArea.tsx — Area de edicion principal con useEditor, recibe el stream SSE del backend y va insertando nodos en vivo mientras Claude genera
• EditorToolbar.tsx — Barra de formato: bold / italic / strike / headings / listas / quote / codigo / link / imagen / tabla / alineacion / undo-redo
• EditorSidebar.tsx — Panel lateral con metadata SEO, TOC navegable, lista de fuentes citadas, Q&A y bloques de codigo detectados
• FreeEditorSidebar.tsx — Variante para el modo editor libre sin generacion previa
• HtmlSourceModal.tsx — Modal para editar el HTML crudo (sanitizado con isomorphic-dompurify antes de aplicarse)
• EditorActions.tsx — Exportar a PDF (jsPDF), Markdown (marked), HTML plano, copiar al portapapeles, guardar como borrador

El contenido generado llega del backend en formato html / markdown / plain_text segun output_format del request, se parsea al schema de TipTap y el usuario puede seguir editando libremente. Todo lo que sale del editor pasa por isomorphic-dompurify antes de persistirse para evitar XSS.

Panel de administracion

Ruta /[locale]/admin protegida por rol de admin verificado en Firebase custom claims. La UI esta organizada en tabs en admin/:

El modelo activo y los max_tokens por longitud se pueden cambiar en caliente desde BackendConfigTab sin tocar env vars ni redesplegar — el backend lee el override con TTL de 60 segundos en AdminConfigRepository.

Partners / white-label

El sistema soporta partners con endpoints publicos bajo /api/v1/[partner]/** (generate, adapt, user/status) para integraciones de terceros con su propia base de usuarios, planes y analytics. Gestionados en el panel admin via 9 componentes dedicados: PartnerDashboard, PartnerDetail, PartnerPlans, PartnerUsers, PartnerSettings, PartnerGuideModal, CreatePartnerModal, PlanEditorModal, PartnersTab.

Cada partner tiene sus propios planes (creditos + precio), sus propios usuarios aislados y endpoints dedicados con autenticacion por API key. La separacion esta en la entidad Partner en core/entities/Partner.ts y PartnerPort en core/ports/PartnerPort.ts.

API publica para desarrolladores

Aparte de la app web, el backend expone una API REST publica documentada con OpenAPI 3 (/docs Swagger, /redoc ReDoc con logo custom inyectado en el schema). Los endpoints publicos son:

La pagina publica para desarrolladores esta en /[locale]/developers, la gestion de API keys del usuario en /[locale]/api-keys y la entidad + use-case de validacion en ApiKey.ts + ValidateApiKeyInput.ts.

Microservicio FastAPI (backend/)

El motor de generacion vive en un microservicio independiente escrito en Python 3.12 + FastAPI, desplegado en Google Cloud Run europe-west1 con escalado a cero. Esta aislado del frontend por dos razones: 1) la ANTHROPIC_API_KEY solo existe en el entorno del backend y jamas se expone al navegador, 2) el microservicio puede redesplegarse sin tocar el frontend (y al reves) porque Cloud Build tiene un filtro included files: backend/** en el trigger.

Estructura real

22 archivos Python · 6.214 lineas organizados por responsabilidad:

backend/
├── app/
│   ├── main.py                    (283 lineas — FastAPI app, CORS, lifespan, health, OpenAPI custom)
│   ├── config.py                  (Settings con pydantic-settings + lru_cache)
│   ├── api/
│   │   ├── routes_generate.py     (849 lineas — POST /v1/generate standard + SSE)
│   │   ├── routes_adapt.py        (516 lineas — POST /v1/adapt multi-plataforma)
│   │   ├── routes_profiles.py     (204 lineas — CRUD /v1/profiles)
│   │   └── routes_admin.py        (339 lineas — /admin/** oculto del OpenAPI publico)
│   ├── auth/
│   │   └── middleware.py          (2 niveles: ADMIN Bearer + STUDIO X-Studio-Key)
│   ├── core/
│   │   ├── engine.py              (1.426 lineas — nucleo de generacion, fallback y citations)
│   │   ├── streaming.py           (225 lineas — wrapper SSE con eventos tipados)
│   │   ├── search_strategy.py     (281 lineas — decision de activar web_search)
│   │   ├── prompts.py             (100 lineas — builder del system prompt)
│   │   └── validators.py          (105 lineas — validacion topic y parametros)
│   ├── db/
│   │   ├── connection.py          (SQLAlchemy async engine + init_db/close_db en lifespan)
│   │   └── repository.py          (578 lineas — AdminConfigRepository, ProfileRepository, HistoryRepository)
│   └── models/
│       ├── database.py            (4 tablas: admin_config, profiles, generations, adaptations)
│       └── schemas.py             (812 lineas — Pydantic v2: requests, responses, enums)
├── prompts/
│   ├── seo-content-generator/SKILL.md    (skill base de generacion)
│   └── adapt/SKILL.md                    (skill de adaptacion a redes)
├── Dockerfile             (multi-stage: builder con gcc + runtime slim, usuario no-root, HEALTHCHECK)
├── cloudbuild.yaml        (build → push → deploy → cleanup revisiones/imagenes antiguas)
└── requirements.txt

Autenticacion en dos niveles

El middleware en app/auth/middleware.py distingue dos identidades que llaman al microservicio:

El frontend nunca expone estos secretos: los route handlers /api/internal/** de Next.js los leen de Firebase App Hosting Secret Manager y los adjuntan en servidor antes de llamar a STUDIO_API_URL. El navegador solo ve la llamada al propio dominio.

Headers adicionales para propagar contexto sin duplicar sesiones:

• X-User-Id — propaga el UID de Firebase Auth al historial
• X-User-Tier — free / premium, determina modelo Claude usado
• X-Request-Id — trace id para correlacionar logs frontend ↔ backend

Modelo de datos (SQLAlchemy 2.0 async)

4 tablas, todas declarativas con Mapped[...] y tipado estricto. Definidas en app/models/database.py:

El engine async soporta tanto SQLite (sqlite+aiosqlite:///./apisdom_studio.db en desarrollo) como PostgreSQL (postgresql+asyncpg://... en produccion) via la variable DATABASE_URL. Las tablas se crean en el lifespan de FastAPI con init_db() y la conexion se cierra limpiamente con close_db() al recibir SIGTERM de Cloud Run.

Docker multi-stage optimizado para Cloud Run

El Dockerfile usa build stage con gcc para compilar dependencias nativas + runtime stage python:3.12-slim con solo el virtualenv copiado. Usuario no-root appuser, PYTHONDONTWRITEBYTECODE=1, PYTHONUNBUFFERED=1, y un HEALTHCHECK que hace urlopen contra /health cada 30s. Arranque con uvicorn --workers 1 --timeout-keep-alive 30 (1 worker porque Cloud Run ya pone 1 contenedor por instancia con concurrency 80).

Configuracion real en Cloud Run (cloudbuild.yaml):

Pipeline de despliegue automatico (trigger en push a main con filtro backend/**):

1. Build de la imagen Docker
2. Push a Artifact Registry europe-west1-docker.pkg.dev/$PROJECT_ID/studio/api
3. Deploy a Cloud Run con la nueva revision
4. Limpieza: borra todas las revisiones excepto las 2 mas recientes
5. Limpieza: borra imagenes del registry excepto las 3 mas recientes

La limpieza automatica mantiene el coste de almacenamiento a cero sin intervencion manual — importante para un proyecto con despliegues frecuentes.

OpenAPI publico con branding custom

FastAPI genera automaticamente /docs (Swagger UI) y /redoc (ReDoc). En main.py se parchea el schema OpenAPI para inyectar:

• info.x-logo — logo horizontal de APISDOM en ReDoc con enlace a https://studio.apisdom.com
• Descripcion markdown extensa con tablas de tipos de contenido, idiomas, plataformas sociales y codigos de error
• Tags organizados (generate, adapt, profiles) con descripciones detalladas
• Rutas /admin/** ocultas del schema publico con include_in_schema=False
• /health (shallow) y /health/deep (verifica DB + formato de ANTHROPIC_API_KEY) fuera del schema publico

El favicon.ico se sirve desde backend/favicon/ como FileResponse estatico para que las pestanas del navegador muestren la marca correctamente en /docs y /redoc.

Calidad de codigo enforced

Sin excepciones en el backend:

mypy src/ --ignore-missing-imports --strict
ruff check src/ --select=E,W,F,B,C90,I,N,UP,S --ignore=E501
pytest

• mypy --strict — todas las funciones publicas con anotaciones completas, Any solo donde el SDK de Anthropic no expone tipos concretos
• ruff con reglas de seguridad (S), bugbear (B), complejidad McCabe (C90), naming (N), pyupgrade (UP) e imports ordenados (I)
• pytest + pytest-asyncio para cobertura de los flujos de generacion, adaptacion y perfiles

Verificadores automaticos de calidad

Cada cambio en el codigo del frontend pasa por una cadena de verificadores antes de poder commitear. El comando npm run verify:all los encadena en secuencia y un precommit de husky los dispara automaticamente. Definido en package.json:

"verify": "tsx scripts/verify-code-quality.ts",
"verify:types": "tsx scripts/verify-type-consistency.ts",
"verify:colors": "tsx scripts/find-hardcoded-colors.ts",
"verify:duplicates": "npx jscpd src --reporters console --min-lines 5 --min-tokens 50",
"verify:all": "npm run verify && npm run verify:types && npm run verify:colors && npm run type-check && npm run verify:duplicates",
"precommit": "npm run verify:all"

Que cubre cada verificador:

Auditorias adicionales en scripts/audit/:

• verify-error-handling.ts — Detecta catch {} vacios, ?? '' en adapters, promesas sin await y accesos a arrays sin chequeo de longitud
• verify-runtime-safety.ts — Detecta JSON.parse sin try/catch, fetch sin check de response.ok, localStorage sin fallback SSR

En el backend la cadena equivalente es:

mypy src/ --ignore-missing-imports --strict
ruff check src/ --select=E,W,F,B,C90,I,N,UP,S --ignore=E501

Con mypy --strict obligatorio: todas las funciones publicas llevan anotaciones de tipo completas y Any solo aparece donde el SDK de Anthropic no expone tipos concretos.

Cifras reales del proyecto

Todas las metricas estan contadas sobre el codigo real del repositorio, no estimadas.

Sistema de creditos real

Definido en pricing.ts — precios en centimos de euro:

• 3 creditos gratis al registrarse (FREE_CREDITS_ON_SIGNUP = 3)
• Adaptaciones multi-plataforma: 1 credito para 1-3 redes, 2 creditos para 4-7 redes
• Coste variable por tipo + longitud: un social_post cuesta 1 credito, un article_long cuesta 5, un tutorial cuesta 4 — tabla completa en credit-costs.ts
• Checkout con Stripe live (pk_live_...), webhook en /api/webhook/route.ts que procesa checkout.session.completed y abona los creditos atomicamente
• Portal de facturacion Stripe en /api/billing/portal/route.ts para gestionar metodo de pago y facturas

Seguridad y cumplimiento

• Autenticacion: Firebase Auth en el cliente, Firebase Admin SDK en los route handlers server-side. El frontend jamas expone la clave del backend — actua como proxy firmado hacia STUDIO_API_URL
• Secrets: gestionados por Firebase App Hosting Secret Manager, declarados como secret: ... en apphosting.yaml (STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, FIREBASE_ADMIN_PRIVATE_KEY, ZOHO_EMAIL_PASSWORD, IP_SALT, BACKEND_ADMIN_KEY...)
• Sanitizacion de HTML: isomorphic-dompurify en todo input/output del editor
• GDPR: export de datos en /api/user/export/route.ts y /api/user/export-pdf/route.ts, borrado de cuenta en /api/user/delete/route.ts con verificacion de borrados previos, certificado GDPR propio en gdpr-certificate.ts
• Newsletter con unsubscribe firmado: token HMAC con UNSUBSCRIBE_SECRET y salt de IP (IP_SALT) para evitar enumeracion
• Rate limiting + fingerprint: @fingerprintjs/fingerprintjs en el trial gratuito para limitar abuso sin registro
• Tests E2E: Playwright 1.58 con flujos criticos (login, generacion, checkout, editor, admin)