# ARCHITECTURE.md — Arquitectura Técnica del Ecosistema 4GatosCoin Este documento describe la arquitectura interna del ecosistema 4GatosCoin, con foco en el panel DevWeb3, los endpoints API, los modelos de datos, el flujo del organismo y las relaciones entre órganos. Está dirigido a ingenieros Web3, desarrolladores backend y colaboradores técnicos. --- # 1. Visión General de la Arquitectura El ecosistema 4GatosCoin está construido como un **organismo vivo**, compuesto por órganos independientes que se sincronizan a través de: - **Next.js App Router** (frontend + API) - **MongoDB** (estado persistente) - **Modelos Mongoose** (esquemas) - **Acciones server-side** - **Panel DevWeb3** (interfaz de ingeniería) - **Organismo Global** (estado centralizado) La arquitectura sigue un patrón **modular**, donde cada órgano tiene: - su propio panel en `app/devweb3//` - sus propios endpoints en `app/api//` - sus propios modelos en `/models` - sus propios tipos en `/types` --- # 2. Diagrama General del Sistema ``` ┌──────────────────────────────┐ │ DevWeb3 Panel │ │ (UI de ingeniería / Next.js)│ └───────────────┬──────────────┘ │ ▼ ┌──────────────────────────────────────┐ │ API Routes (Next.js) │ │ /app/api/* │ │ - Validación │ │ - Normalización de wallet │ │ - Seguridad server-side │ └───────────────┬──────────────────────┘ │ ▼ ┌──────────────────────────────────────┐ │ Modelos Mongoose │ │ /models/* │ │ - Gestures │ │ - Seeds │ │ - Points │ │ - Logs │ │ - OrganismoGlobal │ └───────────────┬──────────────────────┘ │ ▼ ┌──────────────────────────────────────┐ │ MongoDB │ │ Estado persistente del organismo │ │ - Gestos │ │ - Energía │ │ - Semillas │ │ - Puntos │ │ - Memoria │ │ - Latido global │ └──────────────────────────────────────┘ ``` --- # 3. Estructura de Carpetas (Arquitectura Física) ``` app/ api/ → Endpoints del organismo devweb3/ → Panel de ingeniería lib/ → Conexión DB, clientes, utilidades models/ → Modelos Mongoose types/ → Tipos TypeScript components/ → Componentes compartidos ``` ### 3.1. `app/api/*` Cada carpeta representa un órgano o función del organismo: - `gesture/` - `organismo-global/` - `points/` - `seeds/` - `logs/` - `ritugato/` - `clause-stats/` - `milestones/` - `profile/` - `nfts/` - `auth/` Cada endpoint contiene: ``` route.ts - GET - POST - Validación - Acceso a modelos - Respuestas JSON ``` --- # 4. Organismo Global El **Organismo Global** es el núcleo del sistema. Representa el estado vivo del ecosistema: - energía total - territorio - ciclos - latido global - flags del sistema (apagón, rituales activos, etc.) - sincronización entre órganos ### 4.1. Modelo ``` models/OrganismoGlobal.ts ``` ### 4.2. Endpoints ``` GET /api/organismo-global POST /api/organismo-global ``` ### 4.3. Funciones clave - lectura del estado global - actualización controlada - sincronización con gestos y puntos - soporte para eventos rituales --- # 5. Órganos del Ecosistema Cada órgano tiene: - panel en `app/devweb3//` - endpoints en `app/api//` - modelo en `/models` - tipos en `/types` ## 5.1. Gestos El órgano más fundamental. ### Flujo de un gesto ``` Usuario → /api/gesture → Validación → Registro → Puntos → Logs → Organismo Global ``` ### Componentes: - `app/api/gesture` - `models/Gesture.ts` - `app/devweb3/gestos` ### Funciones: - registrar gestos - validar tipos - actualizar puntos - actualizar organismo global - generar logs --- ## 5.2. Puntos Sistema de puntuación del organismo. ### Componentes: - `app/api/points` - `models/Points.ts` - `app/devweb3/points` ### Funciones: - sumar puntos por gesto - consultar puntos por wallet - reglas de puntuación - soporte para temporadas (seasons) --- ## 5.3. Semillas Generación y distribución de semillas. ### Componentes: - `app/api/seeds` - `models/Seed.ts` - `app/devweb3/seeds` ### Funciones: - generación automática - logs de semillas - distribución por actividad --- ## 5.4. Energía Representa la energía vital del organismo. ### Componentes: - `app/api/energia` - `models/Energia.ts` - `app/devweb3/energia` ### Funciones: - lectura de energía global - impacto de gestos - regeneración --- ## 5.5. Logs Registro de eventos internos. ### Componentes: - `app/api/logs` - `models/Log.ts` - `app/devweb3/logs` ### Funciones: - auditoría interna - depuración - trazabilidad --- # 6. Flujo Completo de un Gesto ``` 1. Usuario ejecuta un gesto desde UI externa 2. Llega a /api/gesture 3. Validación: - wallet normalizada - tipo de gesto permitido 4. Inserción en colección Gestures 5. Actualización del sistema de puntos 6. Actualización del Organismo Global 7. Registro en Logs 8. Respuesta al cliente ``` Este flujo es **atómico**: si algo falla, no se actualiza el organismo. --- # 7. Seguridad y Normalización ### 7.1. Normalización de Wallets Todas las wallets pasan por: - lowercase - trim - validación de formato - checksum opcional ### 7.2. Validación de Gestos Los tipos válidos viven en: ``` types/Gesture.ts ``` ### 7.3. Operaciones sensibles Solo se ejecutan server-side: - actualizaciones del organismo - asignación de puntos - generación de semillas - logs internos --- # 8. Extensibilidad El sistema está diseñado para crecer: ### Para añadir un nuevo órgano: 1. Crear carpeta en `app/devweb3//` 2. Crear endpoints en `app/api//` 3. Crear modelo en `/models` 4. Crear tipos en `/types` 5. Conectar con Organismo Global si es necesario ### Para añadir un nuevo gesto: 1. Añadir tipo en `/types/Gesture.ts` 2. Actualizar validación en `/api/gesture` 3. Añadir lógica en puntos/organismo 4. Añadir UI en `devweb3/gestos` --- # 9. Ciclo de Vida del Organismo ``` Gestos → Puntos → Energía → Memoria → Latido → Territorio → Ciclos → Temporadas ``` Cada órgano alimenta al siguiente. --- # 10. Roadmap Técnico - **Aura Individual** - **Sincronización Global** - **Memoria Viva** - **Temporadas** - **Panel OTT** - **Visualización ritual en tiempo real** --- # 11. Licencia Proyecto interno. Acceso restringido a desarrolladores autorizados.