dao/STACK_REALITY.md

# LuxDAO Stack: Reality Check

## The Truth About This Stack

After deep investigation, here's what's REALLY happening:

## 🎭 Three Layers of Reality

### Layer 1: What Docker Compose Shows (The Aspiration)
```yaml
services:
  anvil        ✅ (working)
  contracts    ✅ (working)
  postgres     ✅ (running but unused)
  redis        ✅ (running but unused)
  indexer      ❌ (placeholder - no code)
  api          ❌ (has code but not running)
  graph-node   ❌ (defined but not used)
  ipfs         ✅ (running but unused)
  frontend     ✅ (working)
```

### Layer 2: What Actually Exists (The Implementation)

#### ✅ **WORKING Components:**
1. **Frontend App** (`/dao/app`)
   - Full React/TypeScript application
   - Connects directly to blockchain via RPC
   - Uses Safe API for multisig features
   - No backend dependencies

2. **Smart Contracts** (`/dao/contracts`)
   - Complete Solidity contracts
   - Deploy successfully to Anvil
   - Fully functional governance system

3. **Local Blockchain** (Anvil)
   - Running and accessible
   - Contracts deployed

#### ⚠️ **PARTIALLY IMPLEMENTED:**
1. **API Backend** (`/dao/api/packages/lux-offchain`)
   - **Has full code implementation!**
   - Uses Hono framework, Drizzle ORM
   - Routes for DAOs, proposals, auth, points
   - But **NOT running** (port 3005)
   - Uses PostgreSQL + Redis when running

2. **Subgraph** (`/dao/subgraph`)
   - GraphQL schemas defined
   - Deployment configs for multiple chains
   - But not deployed locally

#### ❌ **NOT IMPLEMENTED:**
1. **Indexer** (`/dao/api/packages/indexer`)
   - Only has Dockerfile
   - No actual code

2. **Graph Node**
   - Docker config exists
   - Not deployed or configured

### Layer 3: What the App Actually Uses (The Reality)

```
Frontend App (port 5173)
    │
    ├──> Direct RPC calls to Anvil (port 8545)
    │    └── Read/write blockchain data
    │
    ├──> Safe API (external)
    │    └── Multisig transaction management
    │
    └──> Mock DAO API (useDAOAPI)
         └── Returns empty arrays (placeholder)
```

## 🔍 The PostgreSQL/Redis Mystery Solved

### They're for the `lux-offchain` API that:
- **EXISTS** (full implementation at `/dao/api/packages/lux-offchain`)
- **IS NOT RUNNING** (should be on port 3005 or 4000)
- **WOULD USE** PostgreSQL for:
  - DAO metadata storage
  - Proposal caching
  - Session management
  - Points/reputation system
- **WOULD USE** Redis for:
  - API response caching
  - Session storage
  - Rate limiting

### The API includes:
```typescript
// Routes that exist but aren't running:
/auth        - Authentication endpoints
/dao         - DAO queries and management
/proposals   - Proposal management
/points      - Reputation/points system
/wallet      - Wallet interactions
```

## 📊 Stack Utilization Report

| Service | Status | Used? | Why It Exists |
|---------|--------|-------|---------------|
| **Anvil** | ✅ Running | ✅ Yes | Local blockchain |
| **Frontend** | ✅ Running | ✅ Yes | User interface |
| **Contracts** | ✅ Deployed | ✅ Yes | Core functionality |
| **PostgreSQL** | ✅ Running | ❌ No | For API (not running) |
| **Redis** | ✅ Running | ❌ No | For API (not running) |
| **IPFS** | ✅ Running | ❌ No | Future: metadata storage |
| **API** | 🟡 Code exists | ❌ No | Not started |
| **Indexer** | ❌ No code | ❌ No | Placeholder |
| **Graph** | ❌ Not deployed | ❌ No | Future: queries |

## 🎯 What You Actually Have

### A Working DAO with:
1. **Full frontend** with wallet connection
2. **Smart contracts** for governance
3. **Local blockchain** for testing
4. **Direct blockchain interaction** (no middleware)

### Infrastructure for (but not using):
1. **Database layer** (PostgreSQL)
2. **Caching layer** (Redis)
3. **File storage** (IPFS)
4. **API backend** (code exists, not running)

## 🚀 To Make Everything Work

### Option 1: Minimal (Current State)
```bash
# Just run what works
make up        # Infrastructure
pnpm dev       # Frontend
# Done! Working DAO
```

### Option 2: Activate the API
```bash
# Start the existing API backend
cd dao/api/packages/lux-offchain
bun install
bun run dev    # Starts on port 3005

# Now PostgreSQL and Redis would actually be used!
```

### Option 3: Full Production Stack
Would need to:
1. Implement the indexer service
2. Deploy the subgraph
3. Configure graph-node
4. Connect IPFS to the app
5. Update frontend to use real API instead of mocks

## 🤔 Why This Architecture?

This is a **production-ready scaffold** that:
- Has all the pieces for a scalable DAO platform
- But only the essential parts are implemented
- Allows gradual activation of features
- Prevents over-engineering for MVP

## 📌 Bottom Line

**You have a working DAO!** The PostgreSQL/Redis/IPFS services are:
- Running but dormant
- Waiting for the API to be activated
- Part of a larger vision that's not fully realized

The stack is like a house with:
- Finished living room and kitchen (Frontend + Contracts)
- Plumbing and electrical installed (PostgreSQL/Redis)
- But no one's using the second floor yet (API/Indexer)

**Current Mode**: Direct blockchain connection (simple, works fine)
**Future Mode**: Full stack with caching, indexing, and optimization