35 lines
5.7 KiB
Markdown
35 lines
5.7 KiB
Markdown
# Plan: Documentar arquitectura de Triple T en Docmost
|
|
|
|
## Context
|
|
|
|
En la reunión de knowledge-transfer técnico ("GFiber Technical Knowledge Transfer", transcript aportado por el usuario como PDF en la raíz del repo), Juan Elorriaga (ingeniero saliente) le explicó a Alejandro (usuario, ingeniero entrante) la arquitectura de **Triple T**, uno de los tres repos del proyecto GFiber. Esta arquitectura es **GCP-based (Terraform, Cloud Run, Firestore, LangGraph/FastAPI)** y no está capturada en ningún lugar del Docmost actual — el espacio "GFiber" solo documenta el stack Next.js/Supabase/Vercel del repo `gfiber-pilot-extension` que vive en este working directory. Son sistemas distintos dentro de la misma iniciativa GFiber (probablemente el backend "legacy"/paralelo que se está gestionando junto con el rediseño Next.js).
|
|
|
|
El usuario pidió explícitamente: extraer la arquitectura de Triple T del transcript y documentarla en una **subpágina nueva dentro de `GFiber_Pilot_Extension`** en Docmost (space "GFiber", id `019e654c-79b5-72fe-9e8c-5edf3af6f64f`, página padre `GFiber_Pilot_Extension` id `019e8dfd-a638-7ba6-96a8-86e733c42b60`), para que quede como referencia del equipo.
|
|
|
|
## Acción
|
|
|
|
Usar `mcp__docmost__create_page` con:
|
|
- `spaceId`: `019e654c-79b5-72fe-9e8c-5edf3af6f64f`
|
|
- `parentPageId`: `019e8dfd-a638-7ba6-96a8-86e733c42b60` (GFiber_Pilot_Extension)
|
|
- `title`: `Triple_T_—_Arquitectura_(GCP-Backend)`
|
|
- `content`: markdown con la siguiente estructura, redactado en español (consistente con el resto del espacio), citando que la fuente es el transcript de knowledge-transfer:
|
|
|
|
1. **Resumen** — qué es Triple T (herramienta de troubleshooting/diagnóstico asistido por IA, basada en grafo), quién la construyó (Juan Elorriaga), relación con Apsel/frontend (mismos 2 proyectos GCP: Apsel y Triple T; no hay proyecto GCP separado para frontend — vive dentro de Triple T por convención, sin razón lógica, solo para minimizar costos).
|
|
2. **Estructura de repos e infra (IaC)** — 3 repos (frontend global + Apsel + Triple T backends separados), cada uno con `infra/{dev,prod,global}` en Terraform siguiendo buenas prácticas (separación de outputs/providers/vars/versions), carpeta `modules/` reutilizable, todo el estado remoto (bucket `Terraform State Gfiber Triple T`, sin state local salvo backups puntuales).
|
|
3. **App (API)** — FastAPI + LangGraph, separación en dominios/servicios/utilidades.
|
|
4. **Pipeline de grafo** — extrae imágenes desde un Google Doc/guía de troubleshooting → las guarda secuencialmente en un bucket GCS (`images`) → las reincorpora al grafo. Un llamado LLM adicional agrupa los nodos del grafo en clusters abstractos ("groups", ej. "initial triage", "diagnóstico de layer físico") para que el checklist final no sea una lista plana. Nota de escalabilidad: si se agregan más guías, se puede escalar a un árbol por guía (no es la única solución posible).
|
|
5. **Firestore** — no-relacional; entornos sandbox/prod/dev (réplicas); colecciones de historial de conversaciones y el grafo en sí.
|
|
6. **Cómputo (Cloud Run)** — contenedores Docker por entorno y repo (frontend dev/prod, Triple T dev/prod, + sandbox de Josías). Prod mantiene 3 containers calientes para evitar cold start/concurrencia; Dev usa mínima infra (ahorro de costos) por lo que es más lento — comportamiento esperado, no bug. Deploy a Cloud Run automatizado desde CI.
|
|
7. **CI (GitHub Actions)** — solo C, no CD real (el "deploy" ocurre dentro del mismo pipeline de CI post-merge). Jobs bloqueantes: linting (Ruff), testing (Pytest backend / Cypress frontend), security (Bandit), secret-leak scanning (TruffleHog, en frontend y backend). Change-detection basado en diffs de paths para solo rebuildear/pushear/deployar cuando cambian app/deps/Docker/CI — aplicado en los 3 repos.
|
|
8. **Dependencias** — Python vía `pyproject.toml` + **uv** (alternativa a pip, escrita en Rust, gestiona versiones de Python por proyecto). Pre-commit hook corre linting + formato + TruffleHog antes de cada commit.
|
|
9. **Documentación existente en el repo** — README a nivel raíz por repo (punto de entrada recomendado), sub-READMEs específicos (ej. cómo y cuándo correr el pipeline de enriquecimiento del grafo), y una carpeta `docs/` autogenerada por IA en refactors grandes.
|
|
10. **Desarrollo local** — requiere `gcloud auth login` (token dura ~6-8h, causa común de fallos silenciosos), workspace con los 3 repos abiertos juntos (para que el agente de código tenga contexto cruzado), Makefile raíz (`make API` levanta backend en :8000, `make dev` levanta frontend en :3000, limpia puertos automáticamente). Local se conecta a la infraestructura remota de **Dev** (no hay backend 100% local). Auth de la app usa Google Workspace (email debe estar whitelisteado en un archivo de config).
|
|
11. **Seguridad** — service account de GCP rotada cada 60 días (obligatorio); keys/.env no están en el repo remoto, se comparten manualmente (Slack/1Password) y deben colocarse en `.env` local por repo; no hay `.env.example` (gap identificado durante la reunión).
|
|
12. **Deuda técnica / puntos de mejora mencionados** — posible eliminación de la tabla de versionado de prompts en BigQuery (Apsel) en favor de inyectar el prompt directamente desde el codebase (reduce latencia, como ya se hace en Triple T); no hay `.env.example` en frontend.
|
|
13. **Nota de fuente** — al pie: "Extraído del transcript de la reunión 'GFiber Technical Knowledge Transfer' (Juan Elorriaga → Alejandro Lembke, con João Guilherme Silva Morossini)."
|
|
|
|
## Verificación
|
|
|
|
- Confirmar que la página se creó correctamente bajo `GFiber_Pilot_Extension` (usar `mcp__docmost__get_page` con el id devuelto, o revisar `mcp__docmost__list_pages` del space).
|
|
- Reportar al usuario el link/id de la nueva subpágina.
|