# maph Documentation

Welcome to the maph (Memory-Mapped Approximate Perfect Hash) documentation!

## 🚀 What is maph?

maph is a high-performance key-value database that provides:
- **O(1) lookups** with perfect hash functions
- **Sub-microsecond latency** for read/write operations
- **Memory-mapped storage** for zero-copy access
- **Lock-free operations** for concurrent access
- **JSON native** support
- **REST API** with web interface

## 📚 Documentation Structure

### Core Documentation
- [Architecture Guide](ARCHITECTURE.md) - System design and internals
- [User Guide](USER_GUIDE.md) - Complete usage guide
- [API Reference](annotated.html) - Detailed API documentation

### Tools & Integrations
- [CLI Documentation](CLI.md) - Command-line tool guide
- [REST API Reference](../integrations/rest_api/API.md) - HTTP endpoints

### Development
- [Contributing Guide](../CONTRIBUTING.md) - How to contribute
- [Changelog](../CHANGELOG.md) - Version history

## ⚡ Performance Highlights

| Metric | Value | Notes |
|--------|-------|-------|
| GET Latency | <100ns | O(1) with perfect hash |
| SET Latency | <150ns | Lock-free atomic updates |
| Throughput | 10M ops/sec | Single thread |
| Batch Throughput | 50M ops/sec | SIMD optimized |
| Memory Overhead | ~512B/entry | Fixed slot size |

## 🎯 Use Cases

maph is ideal for:
- **High-frequency trading** - Sub-microsecond market data access
- **Gaming** - Player session storage with instant lookups
- **IoT** - Device state management at scale
- **Caching** - L2 cache replacement with persistence
- **ML Feature Stores** - Real-time feature serving

## 🔧 Quick Example

```cpp
#include <maph.hpp>

// Create a store with 1M slots
auto store = maph::Maph::create("mystore.maph", 1000000);

// Store JSON data
store->set(R"({"user": "alice"})", R"({"score": 95, "level": 10})");

// O(1) retrieval
auto data = store->get(R"({"user": "alice"})");
```

## 📊 Comparison with Alternatives

| System | maph | Redis | RocksDB | Memcached |
|--------|------|-------|---------|-----------|
| **Lookup** | O(1) guaranteed | O(1) average | O(log n) | O(1) average |
| **Persistence** | mmap | AOF/RDB | SST | None |
| **Memory** | Optimal | 10x overhead | Compressed | In-memory |
| **Concurrent** | Lock-free | Single-thread | Multi-thread | Multi-thread |
| **JSON** | Native | String-based | Binary | String-based |

## 🛠️ Getting Started

### Installation

```bash
git clone https://github.com/yourusername/rd_ph_filter.git
cd rd_ph_filter
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
sudo make install
```

### Basic Usage

```cpp
// C++ API
auto store = maph::Maph::create("data.maph", 100000);
store->set("key", "value");
auto val = store->get("key");

// CLI Tool
maph_cli create mystore --slots 100000
maph_cli set mystore "key" "value"
maph_cli get mystore "key"

// REST API
curl -X POST http://localhost:8080/stores \
  -d '{"name": "mystore", "slots": 100000}'
curl -X PUT http://localhost:8080/stores/mystore/keys/"key" \
  -d '"value"'
```

## 📈 Benchmarks

Benchmarks performed on:
- CPU: AMD Ryzen 9 5950X
- RAM: 64GB DDR4-3600
- OS: Ubuntu 22.04 LTS
- Compiler: GCC 11.3 with -O3 -march=native

### Single-threaded Performance
- Sequential writes: 8.2M ops/sec
- Random reads: 10.1M ops/sec
- Mixed 50/50: 7.8M ops/sec

### Multi-threaded Performance (16 threads)
- Parallel reads: 98M ops/sec
- Parallel writes: 45M ops/sec
- Mixed workload: 62M ops/sec

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.

## 📄 License

MIT License - see [LICENSE](../LICENSE) for details.

## 🔗 Links

- [GitHub Repository](https://github.com/yourusername/rd_ph_filter)
- [API Documentation](annotated.html)
- [Issue Tracker](https://github.com/yourusername/rd_ph_filter/issues)
- [Discussions](https://github.com/yourusername/rd_ph_filter/discussions)