Architecture Patterns

Real-world deployment patterns showing where ekoDB fits in your stack. Choose the pattern that matches your workload.

---

The Core Principle

Separate data processing from data serving. Your app should run fast while your backend handles the complexity of large datasets.

┌─────────────────────────────────────────────────────────────────────┐
│                        Data Tiering Model                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   Data Lake/Warehouse    →    Projection Layer    →    App Layer   │
│   (Snowflake, Databricks)     (PostgreSQL, ekoDB)      (ekoDB/Redis)│
│                                                                     │
│   ▪ All data               ▪ Scoped subsets          ▪ Hot data    │
│   ▪ Batch processing       ▪ By user/group/project   ▪ Sub-ms reads│
│   ▪ Analytics              ▪ Transformed for app     ▪ Sessions    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Not every app needs all three tiers. Match complexity to requirements.

---

Pattern 1: Simple CRUD

Best for: MVPs, internal tools, straightforward applications

┌──────────────┐         ┌──────────────┐
│              │         │              │
│   Client     │ ◄─────► │   ekoDB      │
│   (Web/App)  │         │   (Primary)  │
│              │         │              │
└──────────────┘         └──────────────┘

Configuration:

• Storage Mode: fast or balanced
• Durability: durable for production

When to use:

• Data fits on a single node
• Queries are straightforward
• No complex analytics requirements
• Team wants minimal operational overhead

Example: Internal Dashboard

┌─────────────────┐       ┌─────────────────┐
│  React Admin    │       │     ekoDB       │
│  Dashboard      │◄─────►│                 │
│                 │       │  ▪ Users        │
│  ▪ User mgmt    │  REST │  ▪ Settings     │
│  ▪ Settings     │   +   │  ▪ Audit logs   │
│  ▪ Reports      │  WS   │  ▪ Reports      │
└─────────────────┘       └─────────────────┘

📚 See Basic Operations for CRUD examples and Storage Modes for configuration.

---

Pattern 2: Social Media Platform

Best for: High read volume, real-time feeds, user-generated content

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│  ┌──────────┐    ┌──────────────┐    ┌──────────────┐    ┌───────┐│
│  │ Warehouse│    │  PostgreSQL  │    │    ekoDB     │    │ Client││
│  │ (Spark)  │───►│  (Primary)   │───►│   (Cache +   │◄──►│ Apps  ││
│  │          │    │              │    │   Real-time) │    │       ││
│  └──────────┘    └──────────────┘    └──────────────┘    └───────┘│
│       │                                     │                      │
│       │         Analytics &                 │    Live feeds        │
│       └─────────ML Pipeline                 └────WebSocket         │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Data Flow:

Layer	Technology	Purpose
Cold Storage	Spark/Databricks	Historical analytics, ML training
Primary	PostgreSQL	User accounts, relationships, content
Hot Layer	ekoDB	Feed cache, sessions, real-time notifications
Client	Web/Mobile	User-facing applications

ekoDB Role:

• KV Store: User sessions, auth tokens (Fast mode)
• Document Store: Feed cache by user/group (scoped projections)
• WebSocket: Real-time notifications, typing indicators
• Vector Search: Content recommendations

Example Configuration:

{
  "storage_mode": "fast",
  "durable_operations": false,
  "collections": {
    "sessions": { "ttl": "24h" },
    "feed_cache": { "ttl": "5m" },
    "notifications": { "ttl": "7d" }
  }
}

Why this works:

• PostgreSQL handles writes and complex queries
• ekoDB serves read-heavy feed requests at 200K+ ops/sec
• Scoped caching: each user sees only their feed, not the entire dataset
• WebSocket eliminates polling for real-time features

📚 See Key-Value Store for session management and Basic Operations for real-time subscriptions.

---

Pattern 3: Financial Services

Best for: Transactions, audit compliance, strong consistency requirements

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐         │
│  │  PostgreSQL  │    │    ekoDB     │    │    ekoDB     │         │
│  │   (Ledger)   │───►│  (Read Cache)│    │ (Audit Logs) │         │
│  │              │    │              │    │  Cold Mode   │         │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘         │
│         │                   │                   │                  │
│         │                   │                   │                  │
│         ▼                   ▼                   ▼                  │
│  ┌─────────────────────────────────────────────────────┐          │
│  │                    API Gateway                       │          │
│  └─────────────────────────────────────────────────────┘          │
│                             │                                      │
│                             ▼                                      │
│                      ┌──────────────┐                             │
│                      │   Clients    │                             │
│                      └──────────────┘                             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Data Flow:

Layer	Technology	Mode	Purpose
Ledger	PostgreSQL	ACID	Core transactions, balances
Read Cache	ekoDB	Fast + Durable	Account lookups, balance checks
Audit	ekoDB	Cold + Durable	Immutable transaction history

Critical Configuration:

{
  "ledger_cache": {
    "storage_mode": "fast",
    "durable_operations": true
  },
  "audit_logs": {
    "storage_mode": "cold",
    "durable_operations": true
  }
}

Why Cold Mode for Audit:

• Append-only storage optimized for write throughput
• Compact binary format for efficient disk usage
• Immutable once written
• Regulatory compliance friendly

Security Configuration:

• AES-256-GCM encryption at rest
• TLS/SSL in transit (HTTPS/WSS only)
• JWT authentication with short TTL
• Field-level access control

Example: Transaction Flow

1. Client requests transfer
2. API validates via ekoDB (session check, rate limit)
3. PostgreSQL executes transaction (ACID)
4. PostgreSQL confirms commit
5. ekoDB cache invalidated/updated
6. ekoDB Cold logs audit entry (immutable)
7. Client receives confirmation

📚 See Transactions for ACID operations and Security for encryption details.

---

Pattern 4: E-Commerce Platform

Best for: Product catalogs, shopping carts, search, recommendations

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│  ┌──────────────┐         ┌──────────────────────────────────────┐│
│  │   Warehouse  │         │              ekoDB                    ││
│  │  (Analytics) │         │  ┌────────────┐  ┌────────────────┐  ││
│  │              │────────►│  │  Products  │  │  Sessions/Cart │  ││
│  │  ▪ Sales     │         │  │  (Catalog) │  │    (KV TTL)    │  ││
│  │  ▪ Inventory │         │  └────────────┘  └────────────────┘  ││
│  │  ▪ Trends    │         │  ┌────────────┐  ┌────────────────┐  ││
│  └──────────────┘         │  │   Search   │  │  Vectors for   │  ││
│                           │  │ (Full-text)│  │ Recommendations│  ││
│                           │  └────────────┘  └────────────────┘  ││
│                           └──────────────────────────────────────┘││
│                                          │                        │
│                                          ▼                        │
│                                   ┌──────────────┐               │
│                                   │  Storefront  │               │
│                                   └──────────────┘               │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

ekoDB handles everything in one binary:

Feature	Traditional Stack	ekoDB
Product catalog	PostgreSQL	Document collections
Product search	Elasticsearch	Built-in full-text
Recommendations	Pinecone + ML service	Built-in vector search
Shopping cart	Redis	KV with TTL
Sessions	Redis	KV with TTL
Real-time inventory	Kafka + Redis	WebSocket subscriptions

Example: Product Document

{
  "sku": "WIDGET-001",
  "name": "Premium Widget",
  "description": "High-quality widget for all your needs",
  "price": 29.99,
  "inventory": 150,
  "categories": ["widgets", "premium"],
  "embedding": [0.1, 0.2, 0.3, ...]  // 384-dim for recommendations
}

Search + Recommendations in one query:

// Full-text search
const results = await client.search("products", {
  text: "premium widget",
  fields: ["name", "description"],
  fuzzy: true
});

// Similar products (vector search via search method)
const similar = await client.search("products", {
  vector: currentProduct.embedding,
  vector_field: "embedding",
  vector_k: 5
});

Cart with TTL:

await client.kvSet(`cart:${userId}`, cartData, 86400); // TTL in seconds (24h)

Storage Mode Configuration:

{
  "products": {
    "storage_mode": "balanced",
    "durable_operations": true
  },
  "sessions_cart": {
    "storage_mode": "fast",
    "durable_operations": false
  },
  "order_history": {
    "storage_mode": "cold",
    "durable_operations": true
  },
  "inventory_updates": {
    "storage_mode": "fast",
    "durable_operations": true
  }
}

Data Type	Mode	Durability	Why
Products	balanced	true	Read-heavy but updates matter, large catalog
Sessions/Cart	fast	false	Ephemeral, TTL-based, regenerable
Order History	cold	true	Append-only, compliance, archival
Inventory	fast	true	Real-time updates, must persist

📚 See Storage Modes for detailed mode comparisons and Basic Operations for CRUD examples.

---

Pattern 5: IoT / Time-Series

Best for: Sensor data, logs, metrics, high write throughput

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐         │
│  │   Devices    │    │    ekoDB     │    │  Warehouse   │         │
│  │   (Sensors)  │───►│  Cold Mode   │───►│  (Archival)  │         │
│  │              │    │  (Ingestion) │    │              │         │
│  └──────────────┘    └──────┬───────┘    └──────────────┘         │
│                             │                                      │
│         TCP/WebSocket       │                                      │
│         High throughput     ▼                                      │
│                      ┌──────────────┐                             │
│                      │    ekoDB     │                             │
│                      │  Fast Mode   │◄───── Dashboard/Alerts      │
│                      │ (Real-time)  │                             │
│                      └──────────────┘                             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Dual-Node Strategy:

Node	Mode	Purpose
Ingestion	Cold + Non-Durable	Maximum write throughput
Query	Fast + Durable	Real-time dashboards, alerts

Why Cold Mode for Ingestion:

• Append-only storage optimized for sequential writes
• Minimal disk I/O overhead
• Automatic archival to warehouse via Ripple

Configuration:

{
  "ingestion_node": {
    "storage_mode": "cold",
    "durable_operations": false,
    "ripple": {
      "targets": ["query_node", "warehouse"]
    }
  },
  "query_node": {
    "storage_mode": "fast",
    "durable_operations": true
  }
}

Data Flow:

Sensor → ekoDB Cold (ingest) → Ripple → ekoDB Fast (query)
                             → Ripple → Snowflake (archive)

📚 See Ripples for multi-node sync and Storage Modes for cold mode tuning.

---

Pattern 6: AI / RAG Application

Best for: LLM applications, semantic search, chat with memory

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│  ┌──────────────┐    ┌──────────────────────────────────┐         │
│  │   Documents  │    │            ekoDB                  │         │
│  │   (Upload)   │───►│  ┌────────────┐  ┌────────────┐  │         │
│  │              │    │  │  Vectors   │  │   Chat     │  │         │
│  └──────────────┘    │  │ (Embeddings│  │  History   │  │         │
│                      │  │  + Search) │  │ (Branching)│  │         │
│  ┌──────────────┐    │  └────────────┘  └────────────┘  │         │
│  │     LLM      │◄──►│  ┌────────────┐  ┌────────────┐  │         │
│  │  (OpenAI/    │    │  │   KV for   │  │  Document  │  │         │
│  │   Claude)    │    │  │  Sessions  │  │  Metadata  │  │         │
│  └──────────────┘    │  └────────────┘  └────────────┘  │         │
│                      └──────────────────────────────────┘         │
│                                          │                        │
│                                          ▼                        │
│                                   ┌──────────────┐               │
│                                   │   Chat UI    │               │
│                                   └──────────────┘               │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

ekoDB provides the complete RAG stack:

Component	Traditional	ekoDB
Vector store	Pinecone/Weaviate	Built-in vector search
Document store	PostgreSQL	Document collections
Chat history	Redis/PostgreSQL	Built-in chat with branching
Session state	Redis	KV with TTL
Metadata	PostgreSQL	Same document

RAG Workflow:

// 1. Store documents with embeddings
await client.insert("knowledge_base", {
  content: "ekoDB is a multi-model database...",
  embedding: await embed(content),  // 384-dim
  source: "documentation",
  updated: new Date()
});

// 2. Semantic search for context
const context = await client.search("knowledge_base", {
  vector: await embed(userQuery),
  vector_field: "embedding",
  vector_k: 5
});

// 3. Chat with memory (built-in branching)
const response = await client.chatMessage(sessionId, {
  message: userQuery,
});

Chat Branching:

ekoDB's built-in chat system supports conversation branching:

Main conversation
├── Branch A (what-if scenario)
│   └── Continue exploring...
└── Branch B (alternative approach)
    └── Different direction...

Storage Mode Configuration:

{
  "knowledge_base": {
    "storage_mode": "balanced",
    "durable_operations": true
  },
  "chat_history": {
    "storage_mode": "cold",
    "durable_operations": true
  },
  "sessions": {
    "storage_mode": "fast",
    "durable_operations": false
  },
  "embeddings_cache": {
    "storage_mode": "fast",
    "durable_operations": true
  }
}

Data Type	Mode	Durability	Why
Knowledge Base	balanced	true	Large documents, occasional updates, must persist
Chat History	cold	true	Append-only conversations, audit trail
Sessions	fast	false	Ephemeral user state, TTL-based
Embeddings	fast	true	Frequently accessed vectors, expensive to regenerate

📚 See Chat & RAG for conversation management and Vector Search for embedding operations.

---

Storage Mode Quick Reference

Choose the right combination for your data:

Mode	Durable	Best For	Trade-off	Throughput
fast	true	User data, account state, critical records	Highest durability + speed	~200K ops/sec
fast	false	Sessions, caches, ephemeral data	Maximum speed, data loss on crash OK	~250K ops/sec
balanced	true	Large datasets, production workloads	Good balance for mixed read/write	~150K ops/sec
balanced	false	Development, bulk imports, migrations	Faster imports, not for production	~180K ops/sec
cold	true	Audit logs, compliance, archival	Append-only, immutable, significant space savings	~100K writes/sec
cold	false	High-throughput ingestion, metrics, logs	Maximum write speed, some loss acceptable	~120K writes/sec

When to use each mode:

• fast: Data fits in memory, sub-millisecond reads required
• balanced: Datasets larger than RAM, mixed read/write workloads
• cold: Write-heavy, append-only, archival or compliance data

Durability guidelines:

• durable: true: Financial data, user records, anything you can't regenerate
• durable: false: Caches, sessions, computed data, anything with TTL

📚 See White Paper for configuration options and Performance Benchmarks for detailed metrics.

---

Decision Matrix

If you need...	Use Pattern	Storage Mode	Durability	Key Features
Simple app, minimal ops	1: Simple CRUD	fast or balanced	true	Single node, straightforward queries
High read volume, feeds	2: Social Media	fast	false for cache	WebSocket, TTL-based sessions
Strong consistency, audit	3: Financial	fast + cold	true always	Ledger cache + immutable audit logs
Search + recommendations	4: E-Commerce	balanced + fast	Mixed	Full-text + vectors + KV cart
High write throughput	5: IoT	cold	false for ingest	Append-only chunks, Ripple sync
LLM/RAG application	6: AI/RAG	balanced + cold	true	Vectors + chat history + sessions

Storage Mode by Data Type

Data Type	Recommended Mode	Durability	Examples
User accounts	fast	true	Profiles, preferences, auth tokens
Sessions/cache	fast	false	Login sessions, API cache, rate limits
Large documents	balanced	true	Product catalogs, knowledge bases
Bulk imports	balanced	false	Data migrations, batch uploads
Audit/compliance	cold	true	Transaction logs, access logs
High-volume writes	cold	false	Metrics, IoT sensors, clickstream

---

Anti-Patterns

Don't do this:

Anti-Pattern	Why It Fails	Instead
Everything in one collection	No isolation, hard to scale	Separate by access pattern
Non-durable for financial data	Data loss on crash	Always durable: true
Warehouse queries from app	Slow, expensive	Project to ekoDB first
Polling for real-time	Wasteful, laggy	Use WebSocket subscriptions
Skipping the cache layer	Database overload at scale	Add ekoDB/Redis for hot data
cold mode for random reads	Optimized for sequential writes	Use balanced or fast
fast + non-durable for user data	Data loss on crash	Use durable: true
Same mode for all collections	Missed optimization opportunities	Match mode to access pattern
balanced for ephemeral cache	Unnecessary disk I/O	Use fast + non-durable + TTL

Storage Mode Mistakes:

Wrong Choice	Problem	Correct Choice
cold for user profiles	Slow random reads	fast or balanced
fast for 100GB+ datasets	Memory pressure	balanced or cold
non-durable for orders	Lost transactions	Always durable: true
durable for computed cache	Unnecessary I/O overhead	non-durable + regenerate

---

Migration Path

Start simple, add complexity as needed:

Stage 1: ekoDB only
         ↓
Stage 2: ekoDB + separate cache (if needed)
         ↓
Stage 3: PostgreSQL (writes) + ekoDB (reads/cache)
         ↓
Stage 4: Warehouse + PostgreSQL + ekoDB (full tiering)

Most applications never need Stage 4. Don't prematurely optimize.

Storage Mode Migration:

Start: fast + durable (simple, safe default)
       ↓
Scale: balanced + durable (dataset grows beyond RAM)
       ↓
Optimize: Mixed modes per collection (different access patterns)
       ↓
Enterprise: cold for audit + fast for cache + balanced for data

---

See Also

Core Documentation

• Basic Operations - CRUD operations and queries
• Client Libraries - Language-specific SDKs and examples
• Storage Modes - Fast vs Cold vs Balanced

Advanced Topics

• Performance Benchmarks - Detailed YCSB results
• Vector Search - Semantic search and embeddings
• Chat & RAG - LLM integration and conversation management

Scaling & Operations

• Ripples - Multi-node synchronization and data propagation
• Transactions - ACID operations and isolation levels
• Key-Value Store - High-performance caching with TTL