ResearchOS

Context

ResearchOS manages complex research objects — Experiments, Runs, Notebooks, Papers, Datasets, Models, Artifacts — each with rich business logic. The system must remain testable and allow replacing databases, AI providers, and APIs without modifying core logic.

What I considered

• MVC with Fat Services — rejected: business logic leaks into services, hard to test independently
• Microservices — rejected: operational complexity outweighs benefits for the current scale
• Hexagonal Architecture with DDD — selected: business logic isolated in domain layer, infrastructure behind interfaces

What I chose

Use Domain-Driven Design with Hexagonal Architecture (Ports and Adapters). Each research object is an Aggregate Root. Business logic lives in the domain layer. Infrastructure implements interfaces defined by the domain. Dependency direction: API → Application → Domain. Infrastructure depends on domain, never the reverse.

Trade-offs

• +Replace databases, AI providers, and APIs without modifying business logic
• +Domain logic is fully testable without infrastructure
• +Clear bounded contexts prevent coupling between research modules
• −More files and indirection than a simple MVC approach
• −Team must understand DDD patterns to contribute effectively
• −Interface definitions require upfront design investment

Context

ResearchOS needs vector search, full-text search, JSON document storage, relational queries, and row-level security. Using multiple specialized databases would increase operational complexity.

What I considered

• PostgreSQL + Elasticsearch + Redis — rejected: three systems to operate, synchronize, and debug
• PostgreSQL + ChromaDB — rejected: two vector stores, synchronization complexity
• PostgreSQL only — selected: pgvector for vectors, built-in FTS, JSONB for documents, RLS for security

What I chose

Use PostgreSQL as the single database. pgvector handles vector search. Built-in full-text search handles keyword queries. JSONB stores flexible document structures. Row-Level Security enforces multi-tenant isolation. Extensions provide additional capabilities without additional infrastructure.

Trade-offs

• +Single database to operate, backup, and monitor
• +Vector and keyword search in the same query with JOINs
• +Row-Level Security provides multi-tenant isolation at the database level
• −pgvector performance may not match dedicated vector databases at extreme scale
• −Full-text search lacks advanced features of Elasticsearch
• −Single database is a single point of failure (mitigated by replication)

Context

Research requires finding papers, experiments, and notes by both semantic meaning and exact keywords. Pure vector search misses keyword-heavy queries. Pure BM25 misses semantic similarity.

What I considered

• Vector search only — rejected: poor recall for keyword-heavy queries like "transformer architecture 2017"
• BM25 only — rejected: misses semantically related content with different vocabulary
• Hybrid with RRF — selected: combines vector, BM25, and trigram search with Reciprocal Rank Fusion

What I chose

Implement hybrid search combining three retrieval methods: dense vector search (semantic), BM25 (keyword), and trigram search (fuzzy). Results are merged using Reciprocal Rank Fusion for final ranking. The objective is maximizing recall while maintaining precision.

Trade-offs

• +Significantly better retrieval quality than any single method
• +Handles both semantic queries and exact keyword searches
• +Trigram search catches typos and partial matches
• −Three retrieval methods means three times the computational cost per query
• −RRF parameters require tuning for each domain
• −More complex to debug when search quality issues arise

Context

Every state change in ResearchOS must emit domain events for projections, notifications, embedding generation, and audit logging. The event system needs consumer groups, retry, ordering, and dead letter queues.

What I considered

• Kafka — rejected: operational complexity too high for current scale
• Simple message queue — rejected: no consumer groups, no replay, no ordering guarantees
• Redis Streams — selected: consumer groups, retry, ordering, dead letter queues without Kafka infrastructure

What I chose

Use Redis Streams for the event architecture. Domain events flow through streams to consumer groups. Each consumer group processes events independently — projections, notifications, embedding generation, audit logging. Failed events route to dead letter queues for inspection and replay.

Trade-offs

• +Consumer groups enable independent processing of the same event stream
• +Event replay enables rebuilding projections from history
• +Dead letter queues capture failures without blocking the stream
• −Redis Streams are memory-backed — requires sufficient RAM for event volume
• −Not as battle-tested as Kafka for extreme-scale event streaming
• −Consumer group management requires careful monitoring