dao/ARCHITECTURE.md

LuxDAO Stack Architecture

Overview

The LuxDAO stack is a comprehensive decentralized autonomous organization (DAO) platform built with a microservices architecture. Here's how all the components fit together:

Current Stack Components

🎯 Currently Active & Working

1. Frontend (App) ✅

• Location: /dao/app
• Technology: React, TypeScript, Vite
• Port: 5173 (dev), 3000 (production)
• Purpose: Main user interface for the DAO
• Features:
  • Wallet connection (WalletConnect, MetaMask, etc.)
  • Proposal creation and voting
  • Treasury management
  • Role-based access control
  • Multi-chain support

2. Smart Contracts ✅

• Location: /dao/contracts
• Technology: Solidity, Hardhat, Foundry
• Deployed Contracts:
  • LinearERC20Voting: Token-based voting
  • Governor: Modular governance framework
  • LuxAutonomousAdmin: Autonomous admin functions
  • LuxHats: Role management with Hats Protocol
  • KeyValuePairs: On-chain key-value storage
  • ERC6551Registry: Token-bound accounts

3. Local Blockchain (Anvil) ✅

• Port: 8545
• Purpose: Local Ethereum development network
• Features:
  • Fast block times (3s)
  • Pre-funded accounts
  • Zero gas costs for testing

📦 Infrastructure Services (Running but Underutilized)

4. PostgreSQL ⚠️

• Port: 5432
• Intended Purpose:
  • Store indexed blockchain events
  • Cache DAO metadata
  • Store proposal history
  • Analytics data
• Current Status: Running but not actively used
• Future Use: Will be used by indexer service when implemented

5. Redis ⚠️

• Port: 6379
• Intended Purpose:
  • Cache frequently accessed data
  • Session management
  • Rate limiting
  • Job queues for background tasks
• Current Status: Running but not actively used
• Future Use: Will cache API responses and manage queues

6. IPFS ⚠️

• Ports: 5001 (API), 8080 (Gateway)
• Intended Purpose:
  • Store proposal metadata
  • Store DAO documents
  • Decentralized file storage
• Current Status: Running but not integrated
• Future Use: Store large proposal content off-chain

🚧 Planned/Incomplete Components

7. API Backend (Placeholder)

• Location: /dao/api/packages/offchain
• Intended Purpose:
  • REST/GraphQL API
  • Database interactions
  • Caching layer
  • WebSocket subscriptions
• Status: Dockerfile exists but no implementation

8. Indexer Service (Placeholder)

• Location: /dao/api/packages/indexer
• Intended Purpose:
  • Listen to blockchain events
  • Index and store in PostgreSQL
  • Maintain DAO state
• Status: Dockerfile exists but no implementation

9. Subgraph (Partially Implemented)

• Location: /dao/subgraph
• Purpose: GraphQL API for blockchain data
• Status: Schema defined but not deployed locally

Data Flow Architecture

┌─────────────────────────────────────────────────────────────┐
│                         User Browser                         │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    Frontend App (:5173)                      │
│                  React + TypeScript + Vite                   │
└──────────┬───────────────────────────────────┬──────────────┘
           │                                   │
           │ Direct RPC Calls                  │ (Future: API calls)
           │                                   │
           ▼                                   ▼
┌──────────────────────┐            ┌──────────────────────┐
│   Anvil Blockchain   │            │   API Backend (:4000) │
│      (:8545)         │            │    (Not Implemented)  │
│                      │            └──────────┬───────────┘
│  - Smart Contracts   │                       │
│  - Local Test Chain  │                       ▼
└──────────────────────┘            ┌──────────────────────┐
                                    │   PostgreSQL (:5432)  │
                                    │   Redis (:6379)       │
                                    │   (Underutilized)     │
                                    └──────────────────────┘

Current Implementation Status

✅ What's Working:

1. Frontend connects directly to blockchain via RPC
2. Smart contracts deployed and functional on Anvil
3. All infrastructure services running and healthy
4. E2E tests passing (7/7)

⚠️ What's Not Integrated:

1. PostgreSQL/Redis: Running but no services use them
2. IPFS: Running but not connected to the app
3. API Backend: Not implemented
4. Indexer: Not implemented
5. Subgraph: Not deployed locally

Why PostgreSQL and Redis?

These services are part of a production-ready architecture that would typically include:

PostgreSQL Would Store:

• Indexed blockchain events (faster queries than RPC)
• Proposal metadata and history
• User preferences and settings
• DAO analytics and metrics
• Cached on-chain data for performance

Redis Would Handle:

• API response caching
• Session management
• Rate limiting
• WebSocket pub/sub
• Background job queues
• Real-time notifications

Current App Behavior

The app currently works in "direct mode":

1. Frontend connects directly to Anvil RPC
2. All data fetched directly from blockchain
3. No caching or indexing layer
4. No backend API (everything client-side)

This works for development but would be slow/expensive in production.

Missing Pieces for Complete Stack

1. Indexer Service: Need to implement blockchain event listening
2. API Backend: Need REST/GraphQL API implementation
3. Database Schema: Need to design and implement
4. Caching Strategy: Need to implement Redis caching
5. IPFS Integration: Need to connect for metadata storage
6. Subgraph Deployment: Need local Graph node setup

Recommendation

For a minimal working DAO, you have everything you need:

• Frontend ✅
• Smart Contracts ✅
• Local Blockchain ✅

The PostgreSQL/Redis infrastructure is future-proofing for when you need:

• Better performance (caching)
• Historical data (indexing)
• Complex queries (database)
• Background jobs (queues)

You could simplify the stack by removing unused services for now, or keep them as placeholders for future development.