# AI Context - DeBros Network Cluster

## Table of Contents

- [Project Overview](#project-overview)
- [Product Requirements Document (PRD)](#product-requirements-document-prd)
- [Architecture Overview](#architecture-overview)
- [Codebase Structure](#codebase-structure)
- [Key Components](#key-components)
- [Network Protocol](#network-protocol)
- [Data Flow](#data-flow)
- [Build & Development](#build--development)
- [API Reference](#api-reference)
- [Troubleshooting](#troubleshooting)

## Project Overview

**DeBros Network Cluster** is a decentralized peer-to-peer (P2P) network built in Go that provides distributed database operations, key-value storage, pub/sub messaging, and peer discovery. The system is designed for applications that need resilient, distributed data management without relying on centralized infrastructure.

## Product Requirements Document (PRD)

### Vision

Create a robust, decentralized network platform that enables applications to seamlessly share data, communicate, and discover peers in a distributed environment.

### Core Requirements

#### Functional Requirements

1. **Distributed Database Operations**

   - SQL query execution across network nodes
   - ACID transactions with eventual consistency
   - Schema management and table operations
   - Multi-node resilience with automatic failover

2. **Key-Value Storage**

   - Distributed storage with namespace isolation
   - CRUD operations with consistency guarantees
   - Prefix-based querying and key enumeration
   - Data replication across network participants

3. **Pub/Sub Messaging**

   - Topic-based publish/subscribe communication
   - Real-time message delivery with ordering guarantees
   - Subscription management with automatic cleanup
   - Namespace isolation per application

4. **Peer Discovery & Management**

   - Automatic peer discovery using DHT (Distributed Hash Table)
   - Bootstrap node support for network joining
   - Connection health monitoring and recovery
   - Peer exchange for network growth

5. **Application Isolation**
   - Namespace-based multi-tenancy
   - Per-application data segregation
   - Independent configuration and lifecycle management

#### Non-Functional Requirements

1. **Reliability**: 99.9% uptime with automatic failover
2. **Scalability**: Support 100+ nodes with linear performance
3. **Security**: End-to-end encryption for sensitive data
4. **Performance**: <100ms latency for local operations
5. **Developer Experience**: Simple client API with comprehensive examples

### Success Metrics

- Network uptime > 99.9%
- Peer discovery time < 30 seconds
- Database operation latency < 500ms
- Message delivery success rate > 99.5%

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                    DeBros Network Cluster                   │
├─────────────────────────────────────────────────────────────┤
│                     Application Layer                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │   Anchat    │  │ Custom App  │  │    CLI Tools        │ │
│  │   (Chat)    │  │             │  │                     │ │
│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                      Client API                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │  Database   │  │   Storage   │  │      PubSub         │ │
│  │   Client    │  │   Client    │  │      Client         │ │
│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                    Network Layer                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │  Discovery  │  │   PubSub    │  │     Consensus       │ │
│  │   Manager   │  │   Manager   │  │     (RQLite)        │ │
│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                  Transport Layer                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │   LibP2P    │  │     DHT     │  │      RQLite         │ │
│  │   Host      │  │  Kademlia   │  │    Database         │ │
│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

### Key Design Principles

1. **Modularity**: Each component can be developed and tested independently
2. **Fault Tolerance**: Network continues operating even with node failures
3. **Consistency**: Strong consistency for database operations, eventual consistency for discovery
4. **Security**: Defense in depth with multiple security layers
5. **Performance**: Optimized for common operations with caching and connection pooling

## Codebase Structure

```
network/
├── cmd/                          # Executables
│   ├── node/                     # Network node (bootstrap via flag/auto)
│   │   ├── main.go               # Entrypoint
│   │   └── configmap.go          # Centralized flags/env → config mapping (flags > env > defaults)
│   └── cli/main.go               # Command-line interface
├── pkg/                          # Core packages
│   ├── client/                   # Client API and implementations
│   │   ├── client.go             # Main client (now slimmed)
│   │   ├── connect_bootstrap.go  # Bootstrap helpers
│   │   ├── discovery_aggressive.go # Generic aggressive discovery
│   │   ├── monitoring.go         # Connection monitoring
│   │   ├── pubsub_bridge.go      # PubSub adapter bridge
│   │   ├── implementations.go    # Database, storage, network implementations
│   │   └── interface.go          # Public API interfaces
│   ├── config/                   # Configuration management
│   │   └── config.go             # Node and client configuration
│   ├── constants/                # System constants
│   │   └── bootstrap.go          # Bootstrap node constants
│   ├── database/                 # Database layer
│   │   ├── adapter.go            # Database adapter interface
│   │   └── rqlite.go             # RQLite implementation
│   ├── discovery/                # Peer discovery
│   │   └── discovery.go          # DHT-based peer discovery
│   ├── node/                     # Node implementation
│   │   └── node.go               # Network node logic
│   ├── pubsub/                   # Publish/Subscribe messaging
│   │   ├── manager.go            # Core pub/sub logic
│   │   ├── adapter.go            # Client interface adapter
│   │   └── types.go              # Shared types
│   └── storage/                  # Distributed storage
│       ├── client.go             # Storage client
│       ├── protocol.go           # Storage protocol
│       ├── service.go            # Service (struct/ctor/Close)
│       ├── rqlite_init.go        # Schema initialization
│       ├── stream_handler.go     # Stream handling
│       └── kv_ops.go             # KV operation handlers
├── anchat/                       # Example chat application
│   ├── cmd/cli/main.go           # Chat CLI
│   └── pkg/
│       ├── chat/manager.go       # Chat message management
│       └── crypto/crypto.go      # End-to-end encryption
├── examples/                     # Usage examples
│   └── basic_usage.go            # Basic API usage
├── configs/                      # Configuration files
│   ├── bootstrap.yaml            # Bootstrap node config
│   └── node.yaml                 # Regular node config
├── data/                         # Runtime data
│   ├── bootstrap/                # Bootstrap node data
│   └── node/                     # Regular node data
└── scripts/                      # Utility scripts
    └── test-multinode.sh         # Multi-node testing
```

## Key Components

### 1. Network Client (`pkg/client/`)

The main entry point for applications to interact with the network.

**Core Interfaces:**

- `NetworkClient`: Main client interface
- `DatabaseClient`: SQL database operations
- `StorageClient`: Key-value storage operations
- `PubSubClient`: Publish/subscribe messaging
- `NetworkInfo`: Network status and peer information

**Key Features:**

- Automatic connection management with retry logic
- Namespace isolation per application
- Health monitoring and status reporting
- Graceful shutdown and cleanup

### 2. Peer Discovery (`pkg/discovery/`)

Handles automatic peer discovery and network topology management.

**Discovery Strategies:**

- **DHT-based**: Uses Kademlia DHT for efficient peer routing
- **Peer Exchange**: Learns about new peers from existing connections
- **Bootstrap**: Connects to known bootstrap nodes for network entry

**Configuration:**

- Discovery interval (default: 10 seconds)
- Maximum concurrent connections (default: 3)
- Connection timeout and retry policies

### 3. Pub/Sub System (`pkg/pubsub/`)

Provides reliable, topic-based messaging with ordering guarantees.

**Features:**

- Topic-based routing with wildcard support
- Namespace isolation per application
- Automatic subscription management
- Message deduplication and ordering

**Message Flow:**

1. Client subscribes to topic with handler
2. Publisher sends message to topic
3. Network propagates message to all subscribers
4. Handlers process messages asynchronously

### 4. Database Layer (`pkg/database/`)

Distributed SQL database built on RQLite (Raft-based SQLite).

**Capabilities:**

- ACID transactions with strong consistency
- Automatic leader election and failover
- Multi-node replication with conflict resolution
- Schema management and migrations

**Query Types:**

- Read operations: Served from any node
- Write operations: Routed to leader node
- Transactions: Atomic across multiple statements

### 5. Storage System (`pkg/storage/`)

Distributed key-value store with eventual consistency.

**Operations:**

- `Put(key, value)`: Store value with key
- `Get(key)`: Retrieve value by key
- `Delete(key)`: Remove key-value pair
- `List(prefix, limit)`: Enumerate keys with prefix
- `Exists(key)`: Check key existence

## Network Protocol

### Connection Establishment

1. **Bootstrap Connection**: New nodes connect to bootstrap peers
2. **DHT Bootstrap**: Initialize Kademlia DHT for routing
3. **Peer Discovery**: Discover additional peers through DHT
4. **Service Registration**: Register available services (database, storage, pubsub)

### Message Types

- **Control Messages**: Node status, heartbeats, topology updates
- **Database Messages**: SQL queries, transactions, schema operations
- **Storage Messages**: Key-value operations, replication data
- **PubSub Messages**: Topic subscriptions, published content

### Security Model

- **Transport Security**: All connections use TLS/Noise encryption
- **Peer Authentication**: Cryptographic peer identity verification
- **Message Integrity**: Hash-based message authentication codes
- **Namespace Isolation**: Application-level access control

## Data Flow

### Database Operation Flow

```
Client App → DatabaseClient → RQLite Leader → Raft Consensus → All Nodes
     ↑                                                              ↓
     └─────────────────── Query Result ←─────────────────────────────┘
```

### Storage Operation Flow

```
Client App → StorageClient → DHT Routing → Target Nodes → Replication
     ↑                                                         ↓
     └─────────────── Response ←─────────────────────────────────┘
```

### PubSub Message Flow

```
Publisher → PubSub Manager → Topic Router → All Subscribers → Message Handlers
```

## Build & Development

### Prerequisites

- Go 1.19+
- Make
- Git

### Build Commands

```bash
# Build all executables
make build

# Run tests
make test

# Clean build artifacts
make clean

# Start network node (auto-detects bootstrap vs regular)
make run-node

# Start additional node
make run-node
```

### Development Workflow

1. **Local Development**: Use `make run-node` (auto-detects bootstrap vs regular)
2. **Testing**: Run `make test` for unit tests
3. **Integration Testing**: Use `scripts/test-multinode.sh`
4. **Configuration**: Edit `configs/*.yaml` files

### Configuration Files

#### Bootstrap Node (`configs/bootstrap.yaml`)

```yaml
node:
  data_dir: "./data/bootstrap"
  listen_addresses:
    - "/ip4/0.0.0.0/tcp/4001"
    - "/ip4/0.0.0.0/udp/4001/quic"
database:
  rqlite_port: 5001
  rqlite_raft_port: 7001
```

#### Regular Node (`configs/node.yaml`)

```yaml
node:
  data_dir: "./data/node"
  listen_addresses:
    - "/ip4/0.0.0.0/tcp/4001"
discovery:
  bootstrap_peers:
    - "/ip4/127.0.0.1/tcp/4001/p2p/{BOOTSTRAP_PEER_ID}"
  discovery_interval: "10s"
database:
  rqlite_port: 5001
  rqlite_raft_port: 7001
  rqlite_join_address: "localhost:7001"
```

## API Reference

### Client Creation

```go
import "git.debros.io/DeBros/network/pkg/client"

config := client.DefaultClientConfig("my-app")
config.BootstrapPeers = []string{"/ip4/127.0.0.1/tcp/4001/p2p/{PEER_ID}"}

client, err := client.NewClient(config)
if err != nil {
    log.Fatal(err)
}

err = client.Connect()
if err != nil {
    log.Fatal(err)
}
defer client.Disconnect()
```

### Centralized Defaults & Endpoint Precedence

- Defaults are centralized in the client package:
  - `client.DefaultBootstrapPeers()` exposes default multiaddrs from `pkg/constants/bootstrap.go`.
  - `client.DefaultDatabaseEndpoints()` derives HTTP DB endpoints from bootstrap peers (default port 5001 or `RQLITE_PORT`).
- `ClientConfig` now includes `DatabaseEndpoints []string` to explicitly set DB URLs.
- Resolution order used by the database client:
  1. `ClientConfig.DatabaseEndpoints`
  2. `RQLITE_NODES` environment variable (comma/space separated)
  3. `client.DefaultDatabaseEndpoints()`
- Endpoints are normalized to include scheme and port; duplicates are removed.

Example:

```go
cfg := client.DefaultClientConfig("app")
cfg.BootstrapPeers = client.DefaultBootstrapPeers()
// Optionally pin DB endpoints
cfg.DatabaseEndpoints = []string{"http://db1:5001","db2:5001"}
cli, _ := client.NewClient(cfg)
_ = cli.Connect()
```

### Database Operations

```go
// Create table
err := client.Database().CreateTable(ctx, `
    CREATE TABLE users (
        id INTEGER PRIMARY KEY,
        name TEXT NOT NULL,
        email TEXT UNIQUE
    )
`)

// Insert data
result, err := client.Database().Query(ctx,
    "INSERT INTO users (name, email) VALUES (?, ?)",
    "Alice", "alice@example.com")

// Query data
result, err := client.Database().Query(ctx,
    "SELECT id, name, email FROM users WHERE name = ?", "Alice")
```

### Storage Operations

```go
// Store data
err := client.Storage().Put(ctx, "user:123", []byte(`{"name":"Alice"}`))

// Retrieve data
data, err := client.Storage().Get(ctx, "user:123")

// List keys
keys, err := client.Storage().List(ctx, "user:", 10)

// Check existence
exists, err := client.Storage().Exists(ctx, "user:123")
```

### PubSub Operations

```go
// Subscribe to messages
handler := func(topic string, data []byte) error {
    fmt.Printf("Received on %s: %s\n", topic, string(data))
    return nil
}
err := client.PubSub().Subscribe(ctx, "notifications", handler)

// Publish message
err := client.PubSub().Publish(ctx, "notifications", []byte("Hello, World!"))

// List subscribed topics
topics, err := client.PubSub().ListTopics(ctx)
```

### Network Information

```go
// Get network status
status, err := client.Network().GetStatus(ctx)
fmt.Printf("Node ID: %s, Peers: %d\n", status.NodeID, status.PeerCount)

// Get connected peers
peers, err := client.Network().GetPeers(ctx)
for _, peer := range peers {
    fmt.Printf("Peer: %s, Connected: %v\n", peer.ID, peer.Connected)
}

// Connect to specific peer
err := client.Network().ConnectToPeer(ctx, "/ip4/192.168.1.100/tcp/4001/p2p/{PEER_ID}")
```

## Troubleshooting

### Common Issues

#### 1. Bootstrap Connection Failed

**Symptoms**: `Failed to connect to bootstrap peer`
**Solutions**:

- Verify bootstrap node is running and accessible
- Check firewall settings and port availability
- Validate peer ID in bootstrap address

#### 2. Database Operations Timeout

**Symptoms**: `Query timeout` or `No RQLite connection available`
**Solutions**:

- Ensure RQLite ports are not blocked
- Check if leader election has completed
- Verify cluster join configuration

#### 3. Message Delivery Failures

**Symptoms**: Messages not received by subscribers
**Solutions**:

- Verify topic names match exactly
- Check subscription is active before publishing
- Ensure network connectivity between peers

#### 4. High Memory Usage

**Symptoms**: Memory usage grows continuously
**Solutions**:

- Check for subscription leaks (unsubscribe when done)
- Monitor connection pool size
- Review message retention policies

### Debug Mode

Enable debug logging by setting environment variable:

```bash
export LOG_LEVEL=debug
```

### Health Checks

```go
health, err := client.Health()
if health.Status != "healthy" {
    log.Printf("Unhealthy: %+v", health.Checks)
}
```

### Network Diagnostics

```bash
# Check node connectivity
./bin/network-cli peers

# Verify database status
./bin/network-cli query "SELECT 1"

# Test pub/sub
./bin/network-cli pubsub publish test "hello"
./bin/network-cli pubsub subscribe test 10s
```

---

## Example Application: Anchat

The `anchat/` directory contains a complete example application demonstrating how to build a decentralized chat system using the DeBros network. It showcases:

- User registration with Solana wallet integration
- End-to-end encrypted messaging
- IRC-style chat rooms
- Real-time message delivery
- Persistent chat history

This serves as both a practical example and a reference implementation for building applications on the DeBros network platform.

---

_This document provides comprehensive context for AI systems to understand the DeBros Network Cluster project architecture, implementation details, and usage patterns._
