# README.es.md — Panel DevWeb3 (4GatosCoin)

## Descripción General
DevWeb3 es el panel interno de ingeniería del ecosistema 4GatosCoin.  
Proporciona una interfaz unificada para inspeccionar, probar y extender los sistemas backend que alimentan al organismo: gestos, puntos, semillas, energía, estado global, latido, memoria, rituales y más.

Este panel está diseñado para desarrolladores Web3, ingenieros backend y constructores de protocolos que necesitan acceso directo a las APIs internas y a las estructuras de datos del organismo.

DevWeb3 **no** es un producto para usuarios finales.  
Es un **centro técnico de control** para la arquitectura viva de 4GatosCoin.

---

## Arquitectura
El sistema está construido sobre:

- **Next.js App Router** (frontend + API routes)  
- **MongoDB** (base de datos principal)  
- **Modelos Mongoose** (definición de esquemas)  
- **Acciones server-side** para operaciones internas  
- **Paneles modulares** para cada órgano del ecosistema  
- **Organismo Global** como contenedor central del estado  

### Flujo de alto nivel
```
Panel DevWeb3 (Frontend)
        ↓
Rutas API de Next.js (/app/api/*)
        ↓
Modelos Mongoose (/models)
        ↓
MongoDB (estado del organismo, gestos, logs, semillas, puntos)
```

La arquitectura es modular: cada órgano (energía, semillas, gestos, latido, etc.) tiene su propio panel y sus propios endpoints.

---

## Estructura de Carpetas
Vista simplificada de la estructura relevante:

```
app/
  api/
    auranet/
    auth/
    clause-stats/
    gesture/
    getGestureCounts/
    logs/
    milestones/
    nfts/
    organismo-global/
    points/
    posts/
    profile/
    ritual/
    ritugato/
  devweb3/
    apis/
    aura/
    avatar/
    ciclos/
    components/
    diagnostico/
    eco/
    energia/
    gestos/
    heartbeat/
    logs/
    memoria/
    organismo/
    points/
    rituales/
    sandbox/
    seasons/
    seeds/
    territorio/
    thebeat/
    visualizacion/
lib/
  auranet/
  auth/
  client/
  models/
models/
types/
components/
```

Esta estructura permite localizar rápidamente:

- Endpoints API  
- Paneles  
- Modelos  
- Utilidades compartidas  
- Lógica del organismo  

---

## Funcionalidades Principales

### **1. Organismo Global**
- Ver y actualizar el estado global  
- Inspeccionar el latido (heartbeat)  
- Revisar territorio y ciclos  
- Gestionar flags del sistema (ej. apagón)  

### **2. Gestos**
- Registrar gestos  
- Ver logs de gestos  
- Consultar conteos  
- Validar tipos de gesto  

### **3. Sistema de Puntos**
- Inspeccionar puntos de usuarios  
- Depurar cálculos  
- Validar reglas de puntuación  

### **4. Semillas**
- Ver generación de semillas  
- Inspeccionar logs  
- Depurar distribución  

### **5. Energía**
- Ver energía global  
- Inspeccionar flujo energético  
- Depurar eventos relacionados  

### **6. Logs**
- Ver logs del backend  
- Filtrar por tipo  
- Depurar comportamiento del sistema  

### **7. Sandbox**
- Probar llamadas API  
- Ejecutar experimentos aislados  
- Validar nuevos endpoints  

### **8. Rituales y Memoria**
- Inspeccionar eventos rituales  
- Depurar memoria narrativa  
- Validar disparadores rituales  

---

## Endpoints API
Todas las rutas viven en:

```
app/api/*
```

### Gestos
```
POST /api/gesture
GET  /api/getGestureCounts
```

### Organismo Global
```
GET  /api/organismo-global
POST /api/organismo-global
```

### Estadísticas de Cláusulas
```
GET /api/clause-stats
```

### Logs
```
GET /api/logs
```

### Puntos
```
GET /api/points
```

### Semillas
```
GET /api/seeds
```

### Ritugato
```
GET /api/ritugato
```

### Ejemplo de petición
```bash
curl -X POST https://tudominio.com/api/gesture \
  -H "Content-Type: application/json" \
  -d '{"wallet":"0x123...", "gesture":"pulso_vocal"}'
```

---

## Modelos de Datos
Los modelos viven en:

```
/models
```

Modelos típicos:

- `OrganismoGlobal.ts`
- `Gesture.ts`
- `Seed.ts`
- `Log.ts`
- `Points.ts`
- `Aura.ts`

Cada modelo define:

- esquema  
- validación  
- timestamps  
- relaciones con el organismo  

---

## Cómo Extender el Sistema

### Añadir un nuevo órgano (panel)
1. Crear una carpeta en:
   ```
   app/devweb3/<nuevo-organo>/
   ```
2. Añadir componentes UI.  
3. Crear endpoints en:
   ```
   app/api/<nuevo-organo>/
   ```
4. Añadir modelo si es necesario en:
   ```
   models/
   ```
5. Añadir tipos en:
   ```
   types/
   ```

### Añadir un nuevo endpoint API
1. Crear carpeta en:
   ```
   app/api/<endpoint>/
   ```
2. Añadir `route.ts` con GET/POST.  
3. Importar `dbConnect` desde `/lib/models`.  
4. Usar el modelo correspondiente.  

### Añadir un nuevo gesto
1. Actualizar validación en `/api/gesture`.  
2. Añadir tipo en `/types/Gesture.ts`.  
3. Actualizar panel en `app/devweb3/gestos`.  

---

## Configuración de Desarrollo

### Instalar dependencias
```bash
npm install
```

### Variables de entorno
Crear `.env.local`:

```
MONGODB_URI=tu_conexion
NEXTAUTH_SECRET=...
NEXTAUTH_URL=...
```

### Ejecutar servidor de desarrollo
```bash
npm run dev
```

---

## Consideraciones de Seguridad
- Todas las rutas validan entrada  
- Las wallets deben normalizarse  
- Los tipos de gesto deben validarse  
- No hay escrituras directas desde el frontend  
- Cambios al organismo están controlados  
- Operaciones sensibles requieren ejecución server-side  

---

## Roadmap

### **Fase 5 — Aura Individual**
- Estado del avatar  
- Evolución por gestos  
- Rachas (streaks)  
- Narrativa personal  

### **Fase 6 — Organismo Global**
- Totales de territorio  
- Latido global  
- Sincronización de órganos  
- Primer pulso global  

### **Fase 7 — Memoria Viva**
- Registro narrativo  
- Eventos significativos  
- Evolución del lore  

### **Fase 8 — Estaciones**
- Reinicios globales  
- Cambios de reglas  
- Drops rituales  

### **Fase 9 — Panel OTT**
- Visualización ritual en tiempo real  
- Representación del avatar  
- Animaciones del estado global  

---

## Licencia
Proyecto interno.  
No es open-source.  
Acceso restringido a desarrolladores autorizados.