Data Architecture Overview

GospeLib uses four specialized data stores, each chosen for a specific workload. No single database handles everything — each store is optimized for its access pattern.

Storage Layer Summary

Store	Technology	Port	Purpose
FalkorDB	Redis-based graph DB	6379	All scripture content and relationships — the product
PostgreSQL	PostgreSQL 16 + pgvector	5432	Users, subscriptions, notes, AI embeddings
Redis	Redis 7	6380	Cache, rate limiting, sessions, job queues
Typesense	Typesense 26	8108	Full-text + faceted search

Port Separation

FalkorDB (port 6379) and Redis cache (port 6380) are separate instances. FalkorDB is a Redis-based graph database but it is NOT the application cache. Locally, Redis is port-offset to avoid collision.

When to Use Which Store

graph TD
    Q{"What kind of data?"}
    Q -->|"Scripture text,<br/>relationships,<br/>cross-references"| FDB["FalkorDB<br/>(Graph)"]
    Q -->|"User accounts,<br/>subscriptions,<br/>study notes"| PG["PostgreSQL"]
    Q -->|"Temporary cache,<br/>rate limits,<br/>sessions"| Redis["Redis"]
    Q -->|"Full-text search,<br/>autocomplete"| TS["Typesense"]
    Q -->|"AI embeddings,<br/>vector similarity"| PGV["PostgreSQL<br/>(pgvector)"]

FalkorDB — The Product

FalkorDB stores the scripture knowledge graph: passages, topics, lexicon entries, cross-references, manuscript witnesses, and all the relationships between them. Every graph query in the content service hits FalkorDB.

Use for: Anything related to scripture content, relationships, and traversal.

PostgreSQL — Operational Data

PostgreSQL handles everything that is NOT scripture content: users, subscriptions, billing events, study data (highlights, notes, bookmarks), reading progress, and audit logs. The pgvector extension enables AI embedding storage and similarity search.

Use for: User-generated data, transactional records, embeddings.

Redis — Ephemeral State

Redis handles caching, rate limiting, sessions, and async job queues (via Redis Streams). All data in Redis is expendable — losing it causes cache misses and rate limit resets, not data loss.

Use for: Caching, rate limiting, session preferences, event streams.

Typesense — Full-Text Search

Typesense provides instant full-text search with typo tolerance and faceted filtering. It indexes passages, topics, and lexicon entries synced from FalkorDB during ingest.

Use for: User-facing search, autocomplete, faceted browsing.

Hosting Progression

Store	Phase 1 (Local/Dev)	Phase 2 (Growth)	Phase 3 (Enterprise)
FalkorDB	Docker	K8s StatefulSet	Managed Redis Enterprise
PostgreSQL	Docker	RDS Multi-AZ	Aurora Serverless v2
Redis	Docker	ElastiCache	ElastiCache Cluster Mode
Typesense	Docker	K8s StatefulSet	K8s cluster (dedicated nodes)
Object Storage	MinIO (local)	S3	S3 (multi-region)

Related Pages

• FalkorDB Graph Model — Node types, edge types, Cypher patterns
• PostgreSQL Schema — Tables, migrations, pgvector
• Redis & Caching — Cache keys, TTLs, Streams
• Typesense Search — Collections and indexing strategy