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.

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 high throughput
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) │         │
│  │              │    │              │    │ Balanced 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	Balanced + Durable	Immutable transaction history

Critical Configuration:

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

Why Balanced Mode for Audit:

Durable append-heavy writes with checkpoint batching to disk
Compact on-disk 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

Client requests transfer
API validates via ekoDB (session check, rate limit)
PostgreSQL executes transaction (ACID)
PostgreSQL confirms commit
ekoDB cache invalidated/updated
ekoDB Balanced logs audit entry (immutable)
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": "balanced",
    "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	`balanced`	`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)  │───►│  Fast Mode   │───►│  (Archival)  │         │
│  │              │    │  (Ingestion) │    │              │         │
│  └──────────────┘    └──────┬───────┘    └──────────────┘         │
│                             │                                      │
│         WebSocket           │                                      │
│         High throughput     ▼                                      │
│                      ┌──────────────┐                             │
│                      │    ekoDB     │                             │
│                      │  Fast Mode   │◄───── Dashboard/Alerts      │
│                      │ (Real-time)  │                             │
│                      └──────────────┘                             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Dual-Node Strategy:

Node	Mode	Purpose
Ingestion	Fast + Non-Durable	Highest write throughput of any mode — see Performance Benchmarks
Query	Fast + Durable	Real-time dashboards, alerts

Why Fast Mode for Ingestion:

Highest measured write throughput of any mode
Minimal disk I/O overhead with durability off
Automatic archival to warehouse via Ripple

Configuration:

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

Data Flow:

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

📚 See Ripples for multi-node sync and Storage Modes for storage 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": "balanced",
    "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	`balanced`	`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
`fast`	`true`	User data, account state, critical records	Highest durability + speed
`fast`	`false`	Sessions, caches, ephemeral data	Maximum speed, data loss on crash OK
`balanced`	`true`	Large datasets, production workloads	Good balance for mixed read/write
`balanced`	`false`	Development, bulk imports, migrations	Faster imports, not for production
`balanced`	`true`	Audit logs, compliance, archival	The durable append-heavy choice
`fast`	`false`	High-throughput ingestion, metrics, logs	Highest write speed of any mode; some loss acceptable

When to use each mode:

fast: Data fits in memory, sub-millisecond reads required
balanced: Datasets larger than RAM, mixed read/write workloads

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` + `balanced`	`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	`fast`	`false` for ingest	Highest write throughput, Ripple sync
LLM/RAG application	6: AI/RAG	`balanced`	`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	`balanced`	`true`	Transaction logs, access logs
High-volume writes	`fast`	`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
`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
`fast` for 100GB+ datasets	Memory pressure	`balanced`
`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: balanced for audit + fast for cache + balanced for data

Architecture Patterns

The Core Principle

Pattern 1: Simple CRUD

Pattern 3: Financial Services

Pattern 4: E-Commerce Platform

Pattern 5: IoT / Time-Series

Pattern 6: AI / RAG Application

Storage Mode Quick Reference

Decision Matrix

Storage Mode by Data Type

Anti-Patterns

Migration Path

See Also

Core Documentation

Advanced Topics

Scaling & Operations

The Core Principle​

Pattern 1: Simple CRUD​

Pattern 2: Social Media Platform​

Pattern 3: Financial Services​

Pattern 4: E-Commerce Platform​

Pattern 5: IoT / Time-Series​

Pattern 6: AI / RAG Application​

Storage Mode Quick Reference​

Decision Matrix​

Storage Mode by Data Type​

Anti-Patterns​

Migration Path​

See Also​

Core Documentation​

Advanced Topics​

Scaling & Operations​

The Core Principle

Pattern 1: Simple CRUD

Pattern 2: Social Media Platform

Pattern 3: Financial Services

Pattern 4: E-Commerce Platform

Pattern 5: IoT / Time-Series

Pattern 6: AI / RAG Application

Storage Mode Quick Reference

Decision Matrix

Storage Mode by Data Type

Anti-Patterns

Migration Path

See Also

Core Documentation

Advanced Topics

Scaling & Operations