# README.md — DevWeb3 Panel (4GatosCoin)

## Overview
DevWeb3 is the internal engineering panel of the 4GatosCoin ecosystem.  
It provides a unified interface for inspecting, testing, and extending the core backend systems that power the organism: gestures, points, seeds, energy, global state, heartbeat, memory, rituals, and more.

This panel is designed for Web3 developers, backend engineers, and protocol builders who need direct access to the organism’s internal APIs and data structures.

DevWeb3 is not a user-facing product.  
It is a technical control center for the living architecture behind 4GatosCoin.

---

## Architecture
The system is built on:

- **Next.js App Router** (frontend + API routes)  
- **MongoDB** (primary database)  
- **Mongoose models** (schema definitions)  
- **Server-side actions** for internal operations  
- **Modular panels** for each organ of the ecosystem  
- **Organismo Global** as the central state container  

### High-level flow
```
Frontend Panel (DevWeb3)
        ↓
Next.js API Routes (/app/api/*)
        ↓
Mongoose Models (/models)
        ↓
MongoDB (organism state, gestures, logs, seeds, points)
```

The architecture is intentionally modular: each organ (energy, seeds, gestures, heartbeat, etc.) has its own panel and its own API endpoints.

---

## Folder Structure
Below is a simplified view of the relevant structure:

```
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/
```

This structure allows engineers to quickly locate:

- API endpoints  
- Panels  
- Models  
- Shared utilities  
- Organism logic  

---

## Core Features

### **1. Global Organism**
- View and update global state  
- Inspect heartbeat  
- Check territory and cycles  
- Manage system flags (e.g., blackout/apagón)

### **2. Gestures**
- Register gestures  
- Inspect gesture logs  
- View gesture counts  
- Validate gesture types  

### **3. Points System**
- Inspect user points  
- Debug point calculations  
- Validate scoring logic  

### **4. Seeds**
- View seed generation  
- Inspect seed logs  
- Debug seed distribution  

### **5. Energy**
- View global energy  
- Inspect energy flow  
- Debug energy-related events  

### **6. Logs**
- View backend logs  
- Filter by type  
- Debug system behavior  

### **7. Sandbox**
- Test API calls  
- Run isolated experiments  
- Validate new endpoints  

### **8. Rituals & Memory**
- Inspect ritual events  
- Debug narrative memory  
- Validate ritual triggers  

---

## API Endpoints
All API routes live under:

```
app/api/*
```

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

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

### Clause Stats
```
GET /api/clause-stats
```

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

### Points
```
GET /api/points
```

### Seeds
```
GET /api/seeds
```

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

### Example request
```bash
curl -X POST https://yourdomain.com/api/gesture \
  -H "Content-Type: application/json" \
  -d '{"wallet":"0x123...", "gesture":"pulso_vocal"}'
```

---

## Data Models
Models live under:

```
/models
```

Typical models include:

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

Each model defines:

- schema  
- validation  
- timestamps  
- relations to the organism  

---

## How to Extend the System

### Add a new organ (panel)
1. Create a new folder under:
   ```
   app/devweb3/<new-organ>/
   ```
2. Add UI components inside the folder.
3. Create API endpoints under:
   ```
   app/api/<new-organ>/
   ```
4. Add a model if needed under:
   ```
   models/
   ```
5. Add TypeScript types under:
   ```
   types/
   ```

### Add a new API endpoint
1. Create a folder inside:
   ```
   app/api/<endpoint>/
   ```
2. Add `route.ts` with GET/POST handlers.
3. Import `dbConnect` from `/lib/models`.
4. Use the appropriate model.

### Add a new gesture
1. Update gesture validation in `/api/gesture`.  
2. Add gesture type to `/types/Gesture.ts`.  
3. Update gesture panel under `app/devweb3/gestos`.  

---

## Development Setup

### Install dependencies
```bash
npm install
```

### Environment variables
Create `.env.local`:

```
MONGODB_URI=your_connection_string
NEXTAUTH_SECRET=...
NEXTAUTH_URL=...
```

### Run development server
```bash
npm run dev
```

---

## Security Considerations
- All API routes validate input  
- Wallet addresses must be normalized  
- Gesture types must be validated  
- No direct DB writes from the frontend  
- Organism state changes are controlled  
- Sensitive operations require server-side execution  

---

## Roadmap

### **Phase 5 — Individual Aura**
- Avatar state  
- Gesture evolution  
- Streaks  
- Personal narrative  

### **Phase 6 — Global Organism**
- Territory totals  
- Global heartbeat  
- Organ sync  
- First global pulse  

### **Phase 7 — Living Memory**
- Narrative log  
- Significant events  
- Lore evolution  

### **Phase 8 — Seasons**
- Global resets  
- Rule changes  
- Ritual drops  

### **Phase 9 — OTT Panel**
- Real-time ritual visualization  
- Avatar representation  
- Global state animations  

---

## License
Internal project.  
Not open-source.  
Access restricted to authorized developers.