# CubeCactus Database - Complete Source Code 🌵

**Version:** 1.0.0  
**Java:** 21 LTS  
**Framework:** Spring Boot 3.2.0  
**Build Tool:** Maven 3.6+  

---

## 📦 Package Contents

This package contains the **complete, compilable source code** for CubeCactus distributed database.

```
cubecactus-source/
├── pom.xml                    # Maven build configuration
├── README.md                  # This file
├── BUILD.md                   # Build instructions
├── STRUCTURE.md               # Code structure guide
│
└── src/
    ├── main/
    │   ├── java/com/cube/
    │   │   ├── CubeApplication.java       # Main application
    │   │   ├── storage/                   # LSM Storage Engine
    │   │   │   ├── LSMStorageEngine.java
    │   │   │   ├── WriteAheadLog.java
    │   │   │   └── StorageEngine.java
    │   │   ├── cql/                       # CQL Parser
    │   │   │   ├── CQLParser.java
    │   │   │   └── QueryExecutor.java
    │   │   ├── sql/                       # SQL Parser
    │   │   │   ├── SQLParser.java
    │   │   │   └── SQLExecutor.java
    │   │   ├── gossip/                    # Gossip Protocol
    │   │   │   ├── GossipProtocol.java
    │   │   │   └── GossipMessageHandler.java
    │   │   ├── cluster/                   # Cluster Management
    │   │   │   ├── ClusterNode.java
    │   │   │   └── ClusterManager.java
    │   │   ├── replication/               # Replication
    │   │   │   ├── ReplicationCoordinator.java
    │   │   │   ├── HintedHandoffManager.java
    │   │   │   └── ReadRepairManager.java
    │   │   ├── consistency/               # Consistency Levels
    │   │   │   └── ConsistencyLevel.java
    │   │   ├── shell/                     # Interactive Shell
    │   │   │   └── CubeShell.java
    │   │   ├── api/                       # REST API
    │   │   │   ├── QueryController.java
    │   │   │   ├── SQLController.java
    │   │   │   └── ClusterController.java
    │   │   └── examples/                  # Examples
    │   │       └── SQLExamples.java
    │   └── resources/
    │       └── application.properties
    │
    └── test/
        └── java/com/cube/
            ├── sql/
            │   └── SQLParserTest.java
            └── gossip/
                └── GossipProtocolTest.java
```

---

## 🚀 Quick Build & Run

### Prerequisites
- JDK 21 or later
- Maven 3.6+
- 4GB RAM

### Build
```bash
# Navigate to source directory
cd cubecactus-source/

# Build with Maven
mvn clean package

# Result: target/cubecactus-1.0.0.jar (executable JAR)
```

### Run
```bash
# Run the database
java -jar target/cubecactus-1.0.0.jar

# Server starts on http://localhost:8080
# Health check: curl http://localhost:8080/api/v1/health
```

---

## 📊 Source Code Statistics

- **Total Java Files:** 29
- **Lines of Code:** ~10,000+
- **Packages:** 10
- **Test Files:** 4
- **Documentation Files:** 8+

---

## 🎯 Key Components

### 1. Storage Layer (4 files)
- **LSMStorageEngine.java** - Main storage engine with MemTable, SSTable
- **WriteAheadLog.java** - WAL for durability
- **StorageEngine.java** - Storage interface
- **CubicIndexedStorage.java** - Indexed storage implementation

### 2. Query Processing (6 files)
- **SQLParser.java** - SQL syntax parser
- **SQLExecutor.java** - SQL execution engine
- **CQLParser.java** - CQL syntax parser
- **QueryExecutor.java** - Query execution engine

### 3. Distributed System (8 files)
- **GossipProtocol.java** - SWIM-based membership
- **GossipMessageHandler.java** - Network communication
- **ClusterManager.java** - Cluster coordination
- **ReplicationCoordinator.java** - Data replication
- **HintedHandoffManager.java** - Hint storage
- **ReadRepairManager.java** - Consistency repair

### 4. API Layer (4 files)
- **CubeApplication.java** - Spring Boot application
- **QueryController.java** - Query REST API
- **SQLController.java** - SQL REST API
- **ClusterController.java** - Cluster REST API

### 5. Interactive Shell (1 file)
- **CubeShell.java** - Command-line interface

---

## 🔨 Build Options

### Standard Build
```bash
mvn clean package
```

### Skip Tests (Faster)
```bash
mvn clean package -DskipTests
```

### Run Tests
```bash
mvn test
```

### Install to Local Maven Repo
```bash
mvn clean install
```

### Create Executable JAR
```bash
mvn clean package spring-boot:repackage
```

---

## 🐳 Docker Build (Alternative)

If you don't want to install Maven/Java locally:

```bash
# Create Dockerfile
cat > Dockerfile << 'EOF'
FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /app
COPY pom.xml .
COPY src ./src
RUN mvn clean package -DskipTests

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=build /app/target/cubecactus-1.0.0.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
EOF

# Build image
docker build -t cubecactus:latest .

# Run
docker run -p 8080:8080 cubecactus:latest
```

---

## 📚 Documentation

### Build Documentation
- **BUILD.md** - Detailed build instructions
- **STRUCTURE.md** - Code organization

### Feature Documentation
- **SQL_GUIDE.md** - SQL reference
- **GOSSIP_PROTOCOL_GUIDE.md** - Gossip implementation
- **API_REFERENCE.md** - REST API documentation

---

## 🧪 Testing

### Run All Tests
```bash
mvn test
```

### Run Specific Test
```bash
mvn test -Dtest=SQLParserTest
mvn test -Dtest=GossipProtocolTest
```

### Integration Tests
```bash
# Start server first
java -jar target/cubecactus-1.0.0.jar &

# Run integration tests
mvn verify
```

---

## 🎨 IDE Setup

### IntelliJ IDEA
1. File → Open → Select `pom.xml`
2. Wait for Maven import
3. Right-click `CubeApplication.java` → Run

### Eclipse
1. File → Import → Maven → Existing Maven Project
2. Select directory containing `pom.xml`
3. Run As → Java Application → `CubeApplication`

### VS Code
1. Install "Extension Pack for Java"
2. Open folder
3. Maven panel → Execute → package
4. Run → Start Debugging

---

## ⚡ Quick Start Commands

```bash
# Build
mvn clean package

# Run
java -jar target/cubecactus-1.0.0.jar

# Test API
curl -X POST http://localhost:8080/api/v1/sql/execute \
  -H "Content-Type: application/json" \
  -d '{"sql": "CREATE TABLE test (id TEXT PRIMARY KEY, value TEXT)"}'

# Insert data
curl -X POST http://localhost:8080/api/v1/sql/execute \
  -H "Content-Type: application/json" \
  -d '{"sql": "INSERT INTO test (id, value) VALUES ('"'"'1'"'"', '"'"'hello'"'"')"}'

# Query data
curl -X POST http://localhost:8080/api/v1/sql/execute \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM test WHERE id = '"'"'1'"'"'"}'
```

---

## 🔧 Troubleshooting

### Maven not found
```bash
# Ubuntu/Debian
sudo apt install maven

# macOS
brew install maven

# Windows
# Download from: https://maven.apache.org/download.cgi
```

### Wrong Java version
```bash
# Check version
java -version
javac -version

# Must be 21+
# Install Java 21:
# Ubuntu: sudo apt install openjdk-21-jdk
# macOS: brew install openjdk@21
```

### Build fails
```bash
# Clean and rebuild
mvn clean install -U

# Check dependencies
mvn dependency:tree

# Verify pom.xml
mvn validate
```

---

## 📄 License

Apache License 2.0
Copyright 2026 CubeCactus Project

---

## 🌟 Features Included

✅ LSM Storage Engine  
✅ SQL & CQL Support  
✅ Gossip Protocol (SWIM)  
✅ Data Replication  
✅ Hinted Handoff  
✅ Read Repair  
✅ REST API  
✅ Interactive Shell  
✅ Cluster Management  
✅ Tunable Consistency  

---

## 📞 Support

- GitHub: https://github.com/cubecactus/cubecactus
- Documentation: See `docs/` directory
- Issues: GitHub Issues

---

**Ready to build and deploy CubeCactus!** 🌵🚀

Build with: `mvn clean package`  
Run with: `java -jar target/cubecactus-1.0.0.jar`