Volver a la wiki

Mapa Maestro del Ecosistema CreaRack (Máster para agentes)

Qué es esto. Mapa mental único del ecosistema CreaRack pensado para que un Claude (o dev) nuevo coja el harness rápido: cómo encajan las piezas, los flujos transversales, las reglas operativas, los footguns más peligrosos y el ritual de sesión. Generado por un “Máster en CreaRack” (flujo de trabajo multi-agente, 16 dominios estudiados en paralelo y verificados contra el código real el 28-05-2026), consolidado a partir de 16 briefs de dominio. Encargo de Edu (s94); compartido con el equipo vía tag staff-share.

Regla de uso. Este documento da el MAPA. La fuente de verdad runtime es SIEMPRE el código (config/settings/base.py para versión/IA, bib_stats para cifras del grafo). La doc de contexto (context/agents/dev-*.md) y partes de la Biblioteca tienen drift conocido — verificar contra código.

Producto: CreaRack Pro v1.0.73 · plataforma SaaS multi-tenant para diseño y gestión de datacenters. Empresa: Esferic Labs SL (razón social) = CreaRack (nombre comercial). Stack: Django 6 + Ninja + Channels · PostgreSQL 18 · Valkey 7.2 · Docker/Dokploy/Hetzner. UI del producto en INGLÉS; comunicación del agente y comentarios/commits en español.

1. Visión de una página

CreaRack Pro es un SaaS para que operadores de datacenter diseñen y monitoricen su infraestructura física y de red. Ocho módulos sobre una base multi-tenant común:

Todo corre en contenedores Docker en Hetzner (gestionados por Dokploy), validado por CI en GitHub Actions, y gobernado por un ecosistema externo de tres repos hermanos que NO son el producto pero lo sostienen: Workspace (CreaRackSL-workspace: dashboard, wiki, Biblioteca, MCP server en Cloudflare serverless), claude-method (el harness: hooks, reglas, agentes, skills, onboarding) y Supercontexto/Biblioteca (grafo de conocimiento código↔doc, la memoria externa del equipo, vía tools MCP bib_*).

El equipo es plano de 3 (Edu CEO/Dev, Dani Dev, Txell COO), todos con Claude Code CLI y memorias independientes; el conocimiento compartido vive en CLAUDE.md, context/, la wiki y la Biblioteca.

2. Mapa de componentes y cómo se conectan

2.1 El producto por dentro (apps Django y su acoplamiento)

core es la base de todo: Organization y User (= AUTH_USER_MODEL) son FK de prácticamente todos los modelos; get_current_org(request) e is_admin(user)/has_permission() se importan transversalmente; las políticas RLS de core/migrations/0017 cubren tablas de todas las apps.

core  ◄── racks ◄── blueprints (coloca racks en planos vía BlueprintPlacement)
  ▲        ▲   ▲
  │        │   └── network (auto-link DeviceProfile↔Device por IP; stencil; PortConnection)
  │        │
  │        └── monitoring (MonitoringTarget FK a racks.Device; lee management_config cifrado)
  │
  ├── network ──► monitoring (configure_observatory crea MonitoringTarget + OIDs)
  ├── signage ──► monitoring (¡publish/deploy vive en monitoring/api/signage/, no en signage/!)
  └── terminal/agent ──► monitoring (Sentinel empuja métricas) + network (discovery proxy)

Acoplamientos que sorprenden (verificados en código, contra-intuitivos):

2.2 Frontend (patrón híbrido, no SPA)

Django renderiza HTML (templates + partials HTMX); JS modular ES6 vanilla añade interactividad sobre el DOM. Alpine.js cubre widgets reactivos puntuales (sin x-html por CSP). No hay React/Vue en el producto. Konva.js para canvas (editores), ECharts para gráficas, xterm.js para terminal (corre en el Local Agent, no en la página).

Núcleo CSP-safe: core/middleware/csp.py aplica nonce por request, script-src sin unsafe-inline → prohibido onclick= inline. La solución es event delegation en base.js con atributos data-action="fn" resueltos por dot-notation contra window. CSP es Report-Only en dev, Enforce en prod (un handler inline “funciona” en dev y rompe en prod).

Dos mundos JS coexisten (footgun crítico): static/js/*.js (218 archivos, el código vivo) vs frontend/src/*.ts (Vite+TS, migración estancada — solo echarts-loader.ts y terminal.ts se consumen en runtime). Editar el .ts equivocado no cambia nada.

2.3 Infra / despliegue (PROD y STAGE)

Internet ─HTTPS─► Traefik v3.6.7 (SSL Let's Encrypt) ─► web (Daphne ASGI :8000)
                                                          ├─ DB vía pgbouncer ─► PostgreSQL 18
                                                          ├─ cache/broker ─► Valkey 7.2
                                                          └─ métricas ─► VictoriaMetrics :8428

2.4 El ecosistema de gobernanza (workspace + Biblioteca + harness)

Claude Code (Edu/Dani/Txell) ──┬── consulta ──► MCP server (workspace.crearack.com/api/mcp)
                               │                    ├─ bib_*  (grafo + Archivo Maestro RAG)
                               │                    ├─ wiki_* (ciclo de vida wiki)
                               │                    └─ workspace/holded/github/email/infra
                               ├── pre-commit hook ──► bib_report_change obligatorio
                               └── SessionStart hook ──► git pull + hot-cache + hora local + sync

Repos (.py/.ts/.md) ──extractores AST/OpenAPI/docs──► Cloudflare D1 (nodes/edges/chunks/wiki)
                                              embeddings BGE-M3 + síntesis Gemma 4 / curación Haiku

3. Flujos transversales

3.1 Auth + aislamiento multi-tenant (ORM + RLS)

Pipeline de middleware (config/settings/base.py, orden REAL): Prometheus → MetricsIPRestriction → Security → WhiteNoise → RateLimit → Session → CSRF → Auth → Account(allauth) → Impersonation → AdminPaths → ModuleGating → TenantRLS → … → CSP.

3.2 Stack IA — Gemma 4 mono-proveedor (Regla 8)

Toda llamada LLM del producto usa un modelo único gemma-4-26b-a4b-it vía Google AI Studio Paid Tier (SDK google-genai), con Claude Haiku 4.5 como red de seguridad. Diseño (refactor s61): cambiar de modelo = 1 env var, no N ediciones. Los model strings resuelven contra config/settings/base.py (GEMMA4_GENAI_MODEL, EDGE_AI_GOOGLE_GENAI_MODEL, ANTHROPIC_HAIKU_MODEL).

Cuatro flujos IA con provider independiente: Auto-Plan visión (AUTOPLAN_PROVIDER) → google_genai_driver.py; CNS/Tutor/MIB/Explain (EDGE_AI_PROVIDER) → factory get_provider(); chain genérica ai_fallback() (google_genai → Claude); workspace usa Gemma 4 (Help/Oráculo/Tutor/traducción) + Haiku (curación).

Invariantes Gemma 4 (replicados en driver + router + provider): sampling temp 1.0 / top_p 0.95 / top_k 64; response_mime_type="application/json" load-bearing (sin él la calidad cae ~100%→75%); NO enviar safety_settings ni thinking_config (Gemma open-weights devuelve 400). Salida siempre por sanitizeRawJson + fallback regex (Gemma rompe el JSON ~1/20-30 runs). Prohibidos en runtime: OpenRouter (retirado s55), Gemini, DeepSeek (s66), OpenAI, free tier, self-host PROD. Cambio de modelo = ADR + Regla 8 + AI_CONFIG.md en el mismo commit.

3.3 Despliegue PROD/STAGE (push → CI → Dokploy)

git pull --rebase origin main → git push a main → (GitHub Actions ci.yml como gate de validación) + (webhook GitHub → Dokploy → git pull + build Dockerfile.prod → recrea containers). [skip ci] PROHIBIDO (Regla 16): Dokploy filtra “skip” y omite el deploy silenciosamente, y rompe CF Pages + Bibliotecario-Ingest. Tras push: gh run list --limit 1 (Regla 14). SSL lo termina Traefik (SECURE_SSL_REDIRECT=False a propósito). CONN_MAX_AGE=0 inviolable con Daphne ASGI (revertido mal 4 veces).

3.4 Ciclo de la Biblioteca: report_change → commit → reindex

  1. Tras editar código, antes de commitear: bib_report_change(file_path, change_type) por cada archivo.
  2. El hook pre-commit bib_report_check.py bloquea el commit si un fichero MODIFIED no tiene report en la ventana de 10 min. Bypass: BIB_SKIP=1 git commit (queda logueado en Pulse).
  3. El reindex AST (cada 10 min, cron STAGE) recoge el cambio y re-popula nodos/edges.
  4. Al mergear/push a main: post-merge-ingest.yml decide crear/actualizar páginas wiki (filtro $0 → triage Haiku → deep Haiku) vía tools wiki_*.

Identidad del grafo = qualified_name (POST:/api/racks/, racks.models.Device, doc:CLAUDE.md), nunca el id. Reindexar es idempotente.

3.5 Local Agent — el puente a IPs privadas

El SaaS en Hetzner (EU) no alcanza IPs privadas del cliente. El Local Agent (CreaRackAgent.exe, Windows) corre en el PC del operador y puentea: SSH/SFTP en navegador, discovery/SNMP de Auto-Provision, Sentinel 24/7 (métricas a VictoriaMetrics + anomalías CNS), y deploy de Signage (WebDAV). El frontend decide con isPrivateIPAddress(ip); los endpoints /api/network/... que tocan IPs privadas devuelven HTTP 422 USE_LOCAL_AGENT y el navegador reenvía al agente en localhost:5050. Release del agente = docs + tag git + .exe como asset (los 3).

4. Las 26 Reglas de Oro destiladas a lo operativo

Detalle: CLAUDE.md §1 + context/RULES_DETAIL.md. Marcadas [HOOK] las que bloquea un check automático del pre-commit.

#ReglaQué significa al trabajar
0Biblioteca primerobib_ask → bib_search_semantic → bib_context_query/bib_app_summary → bib_impact_query → read_guide ANTES de tarea no trivial. También antes de explicar la UI al usuario.
1IdiomaComunicación del agente SIEMPRE en español. La UI del producto va en inglés.
2No duplicar códigoBuscar antes de crear.
3Docs incrementalesCommit funcional → actualizar CLAUDE.md, README, CHANGELOG, RELEASE_NOTES, context/. (TASK.md JUBILADO s185 → estado vivo en Supercontexto STATE.md/NEXT.md + Gestor del workspace.)
4GitHubgit pull --rebase origin main SIEMPRE antes de push. Push inmediato, sin [skip ci].
5Modularización[HOOK] Máx 500 LOC lógica/módulo; warning a 400.
6ConfirmaciónPlan antes de tareas complejas.
7Botones UISOLO TEXTO, nunca iconos ni glyphs Unicode (←→✓×). Clases btn-action/danger/warning/success/neutral. Tooltip title obligatorio.
8Modelos IAGemma 4 único vía google-genai a AI Studio; Haiku alternativo. Centralizado en base.py. Cambio = AI_CONFIG.md + ADR + Regla 8 mismo commit.
9Nuevas dependenciasVerificar licencia + SECURITY_AUDIT.md + core/licenses.py.
10Subagentes Opusmodel: "opus" en general-purpose y Plan; Explore hereda ligero.
11Release NotesRELEASE_NOTES.md en cada cambio funcional/infra.
12WorklogWORKLOG.md del workspace al cierre. Resumen coloquial (para Txell) + Detalle técnico.
13No fakesNunca mocks ocultos/datos hardcoded que simulen funcionalidad real sin avisar.
14Verificar CI tras pushgh run list --limit 1. CI rojo + Dokploy verde = errores invisibles.
15HTTP 200 ≠ éxitoScripts con APIs desenvuelven body, detectan errors[], exit ≠ 0 en fallo.
16Nunca [skip ci]Rompe Dokploy + CF Pages + Ingest. Excepción única: emergencia autorizada.
17Infra no en PC personalCrons/servicios críticos en Hetzner/CF Workers/GH Actions, nunca Task Scheduler local.
18Pre-commit gemelo de CI[HOOK] Cada check de CI tiene gemelo local.
19Supercontexto arranque/cierrePRIMER paso leer STATE.md + NEXT.md; ÚLTIMO actualizar STATE + LOG + NEXT.
20Push vs PR (híbrido)Ver §4.1. Auto-merge cuando CI verde.
21Tamaño de commitBug fix ≤80 LOC (1 fix = 1 commit). Feature ≤400 LOC/commit.
22Definitivo > rápidoEl camino definitivo salvo riesgo objetivo cuantificable.
23No dejar deudasCada tarea cierra con deudas resueltas o documentadas (plan/dueño/fecha).
24Igualdad de accesos staffCambios en harness/perfil/credenciales → 3 onboardings + docs en el MISMO commit.
25Zona horariaTodo en Europe/Madrid. Usar la línea [Local time] del hook, no el currentDate UTC.
26Agentes/MCP especializadosUI → design-collaborator. Wiki → wiki_create_page. Grafo → bib_*. No defaultear a general-purpose.

4.1 Push vs PR (Regla 20) + auto-merge

4.2 Directrices Karpathy (CLAUDE.md §12)

  1. Pensar antes de codificar — verbalizar suposiciones; varias interpretaciones → presentarlas.
  2. Simplicidad primero — el mínimo código; sin features especulativas.
  3. Cambios quirúrgicos — tocar solo lo imprescindible; dead code preexistente → mencionar, no borrar.
  4. Ejecución dirigida por objetivo — transformar tareas en objetivos verificables.

5. Footguns más peligrosos del ecosistema

Ordenados por probabilidad de morder a un agente nuevo.

  1. Drift de IA en doc/Biblioteca: dicen Gemini/OpenRouter/DeepSeek/Ollama, temp 0.1, 2 endpoints Auto-Plan. Todo histórico/retirado. El runtime real es Gemma 4 + chain google_genai → Claude. RULES_DETAIL.md Regla 8 aún dice “Gemma vía OpenRouter”. Verificar contra base.py + AI_CONFIG.md.
  2. Dos mundos JS (static/js vivo vs frontend/src Vite estancado): editar el .ts equivocado no cambia nada (salvo echarts-loader.ts/terminal.ts).
  3. RLS solo USING, sin WITH CHECK: protege lectura cross-tenant, NO escritura. Siempre filtrar por organization=org.
  4. Cifrado de credenciales atado a SECRET_KEY: rotar DJANGO_SECRET_KEY rompe el descifrado de TODAS las StoredCredential. Hay además una DEV_KEY hardcodeada de fallback (deuda de seguridad conocida).
  5. CONN_MAX_AGE=0 con Daphne ASGI es inviolable (revertido mal 4 veces; satura max_connections).
  6. Dokploy / Swarm / Traefik — qué NO tocar: nunca docker swarm leave; nunca docker compose up/down manual en el servidor (containers sin labels Traefik → 404); editar .env directo se sobreescribe en deploy (usar panel); el webhook usa la IP por la que accedes al panel (entrar por NetBird grabó IP privada → auto-deploy muerto). Labels Traefik los inyecta Dokploy en cada deploy.
  7. NetBird nameserver “all domains” (catch-all) rompe el DNS de toda la máquina: acotar a netbird.cloud. Resolve-DnsName siempre falla para *.netbird.cloud (no es fallo real).
  8. Auto-Plan: response_mime_type JSON + sin safety_settings/thinking_config son load-bearing (quitar el primero baja calidad 100%→75%; enviar los otros da 400).
  9. sanitizeRawJson en TODA síntesis Gemma 4: rompe el JSON ~1/20-30 runs. Nunca JSON.parse directo.
  10. bib_ask puede dar 429 (cuota AI Studio) o timeout (cold start >80s → 524): caer a bib_search_semantic + lectura directa de código.
  11. DELETE /api/racks/{id} hace HARD delete (CASCADE borra Devices + ConfigBackups), pese a que la doc dice soft. La vista rack_editor (GET) NO filtra por org. El auto-save es SYNC destructivo.
  12. Crear/editar wiki vía MCP (wiki_create_page), no a mano: commitear .md a mano en un PR con código hace que Bibliotecario-Ingest re-genere y borre el campo product → la página no lista. Los [[wikilinks]] del cuerpo NO son enlaces en la web (solo backlinks related[]).
  13. Doble fuente de config pytest: pytest.ini (settings dev) vs pyproject.toml (settings test). El split RLS en CI es intocable (race en DROP ROLE → flaky).
  14. Los checks del pre-commit corren desde claude-method/harness/ (fuente única en ejecución desde el 05-08-2026): ya no hay copias scripts/harness/ que puedan desincronizarse. install_hooks.sh solo escribe el git hook pre-commit; los otros dos hooks (pre-push, commit-msg) los pone el instalador convergente install-git-hooks.ps1.
  15. Opus 4.8 baja el effort a high pisando el xhigh del settings al actualizar → adherencia floja a reglas. Fix: /effort xhigh + env CLAUDE_CODE_EFFORT_LEVEL=xhigh.
  16. Doble /signage en URLs CMS (/api/signage/signage/...) — patrón real, no typo. Y 7/12 vendors de signage caen al fallback generic_snmp (sin push real); el camino vivo es SpinetiX.
  17. PowerShell & solitario manda a background, no encadena — usar ;, && o call operator & <ruta>.
  18. Crons wiki del Bibliotecario migrados a systemd STAGE (schedule: comentado en GH Actions desde s66) — no buscar el log de Lint/Curator en GitHub Actions. El reindex del grafo sí está activo.

6. Glosario de términos propios

7. Cómo arrancar y cerrar sesión (Regla 19) + ritual “Apaga”

Arranque: (1) hora local — el hook SessionStart inyecta [Local time] … Europe/Madrid (esa línea manda, no el currentDate UTC); verificar /effort = xhigh. (2) Supercontexto — leer STATE.md + briefings/NEXT.md (en CreaRackSL-workspace/public/supercontext/). (3) Biblioteca primero (Regla 0). (4) la sesión se ancla en C:\dev\CreaRack-Pro.

Trabajo: respetar las 26 reglas; agentes/MCP especializados antes que general-purpose (Regla 26); antes de commitear código modificado bib_report_change por archivo (el hook bloquea); antes de push git pull --rebase origin main; tras push de código gh run list --limit 1.

Ritual “Apaga” (palabra clave de cierre — ejecutar SIN preguntar; disparado por “Apaga”/“lo dejamos”): (1) Supercontexto si se tocó (STATE + LOG; NEXT si cambia backlog; reconciliar 🔔 Pendientes contra estado real). (2) WORKLOG.md del workspace (Resumen coloquial + Detalle técnico). (3) tag opcional supercontext/sesion-N-done. (4) Sync Cascade si se tocó src/content/wiki/*.md. (5) commits + push (git pull --rebase antes; nunca [skip ci]). (6) verificar CI. (7) memorias + MEMORY.md. (8) backup memoria (claude-method/harness/claude-backup.ps1 -PushGit).

NUNCA sugerir cierre ni preguntar “¿cerramos o seguimos?” — Edu decide cuándo parar.

8. Los 16 dominios estudiados (para profundizar)

El detalle profundo de cada dominio se estudió en un brief dedicado (verificado contra código). Para profundizar en cualquiera: bib_app_summary(app="…") + bib_ask + lectura directa del código; los briefs completos del Máster los custodia Edu (C:\dev\crearack-master\briefs\, regenerables con el flujo master-crearack).

Necesito…Dominio
Auth, tenancy, RLS, permisos, Credential Store, middlewarecore
Rack Editor (Konva, devices, auto-save, stencils, export)racks
Map Editor + Auto-Plan AI (visión, pipeline imagen→racks)blueprints
Observatory, CNS, ITSM, VictoriaMetrics, providers IAmonitoring
Auto-Provision, discovery, SNMP, VendorProfile, nmapnetwork
Digital Signage CMS, SpinetiX, SVG composer, publishsignage
Terminal SSH, Local Agent, Sentinel, fleet, JWTterminal
Settings por entorno + stack IA (Regla 8, model strings)config-ai
Frontend (HTMX/Alpine/Konva/ECharts, CSP data-action, CSS)frontend
Docker, CI, Dokploy, Traefik, NetBird, backups, servidoresinfra-devops
Tests (pytest/RLS/fitness/E2E), tooling, pre-commit harnesstests-tooling
Workspace (Astro/CF Workers/D1/MCP server, Oráculo)workspace-app
Supercontexto/Biblioteca (grafo, ingest, reindex, bib_*)supercontexto
Contenido wiki (6 wikis, taxonomía slugs, ADR/runbook)wiki-content
Harness claude-method (hooks, propagación, onboarding)harness-method
Las 26 Reglas + Karpathy + ritual de sesióngolden-rules

Aviso transversal de fidelidad: los 16 briefs coinciden en que context/agents/dev-*.md, el README/FEATURE_CATALOG (conteos JS/templates) y partes de la Biblioteca tienen drift conocido. La fuente de verdad es el código (config/settings/base.py, bib_stats en vivo). Verificar siempre.


Generado por el flujo de trabajo dinámico master-crearack (Claude Opus 4.8) el 28-05-2026. Última actualización: 28-05-2026.

Véase también

Subir