Document: 20-search-architecture.md
Version: 1.0.0

Purpose

This document defines the search architecture used across all Rundown projects.

Search enables users to efficiently discover content, products, services, and other information within an application. The search architecture should prioritize simplicity, performance, and scalability while remaining appropriate for the project's requirements.

Search Philosophy

Search should solve the business problem with the simplest appropriate solution.

Dedicated search infrastructure should only be introduced when measurable requirements justify the additional operational complexity.

Rundown favors incremental scalability over premature optimization.

Responsibilities

The search layer owns:

• Content discovery

• Product discovery

• Filtering

• Sorting

• Relevance ranking

• Search indexing (when applicable)

Non-Responsibilities

The search layer should not own:

• Business data

• Content management

• Database design

• Frontend presentation

• SEO

Search improves access to data but does not become the source of truth.

Search Strategy

Rundown uses a progressive search strategy.

Level 1 — PostgreSQL Search (Default)

Suitable for:

• Marketing websites

• Company websites

• Blogs

• Portfolios

• Small ecommerce stores

Advantages:

• No additional infrastructure

• Low operational cost

• Simpler deployment

• Easy maintenance

This should be the default choice for new projects.

Level 2 — Meilisearch

Introduce Meilisearch only when PostgreSQL search no longer meets performance or feature requirements.

Typical use cases include:

• Large ecommerce catalogs

• Thousands of products

• Complex filtering

• High query volume

Meilisearch provides:

• Fast full-text search

• Typo tolerance

• Faceted search

• Relevance ranking

Level 3 — Enterprise Search

Solutions such as Elasticsearch or OpenSearch should only be considered for projects with enterprise-scale search requirements.

These technologies introduce significant operational complexity and are outside the standard Rundown architecture.

Search Sources

Search may include:

• Products

• Blog posts

• Portfolio projects

• Documentation

• Team members

• Services

Every searchable entity should represent a meaningful business concept.

Search Experience

Good search should provide:

• Fast results

• Relevant ranking

• Helpful empty states

• Typo tolerance (when supported)

• Clear filtering

• Predictable sorting

Search should help users complete tasks rather than simply return data.

Filtering

Filtering should represent business attributes.

Examples:

Products:

• Category

• Brand

• Price

• Availability

Portfolio:

• Industry

• Service

• Technology

Blog:

• Category

• Author

• Tags

Avoid filters that exist solely because of database structure.

Sorting

Typical sorting options include:

• Relevance

• Newest

• Oldest

• Price

• Alphabetical

Sorting should remain consistent across similar content types.

Performance

Search performance should prioritize:

• Efficient indexing

• Minimal query latency

• Predictable response times

• Cached results where appropriate

Search should remain responsive under normal production workloads.

Security

Search should respect authorization rules.

Users should never discover content they are not permitted to access.

Private content should remain excluded from public search indexes.

Monitoring

Search quality should be reviewed periodically.

Metrics may include:

• Search success rate

• Empty result frequency

• Popular queries

• Slow queries

Monitoring should support iterative improvements rather than unnecessary optimization.

Engineering Decision

Progressive Search Strategy

Status: Accepted

Decision

Rundown adopts a progressive search strategy:

1. PostgreSQL Search

2. Meilisearch (when justified)

3. Enterprise search platforms only for exceptional cases

Reasoning

This approach:

• Minimizes infrastructure.

• Reduces operational costs.

• Keeps deployment simple.

• Allows projects to scale without redesigning the application.

Search Checklist

Before implementing search, verify:

• Does the project require search?

• Is PostgreSQL sufficient?

• Are searchable entities business-focused?

• Are filters meaningful?

• Are authorization rules enforced?

• Has performance been reviewed?

Summary

Search should evolve with the application's needs.

By adopting a progressive strategy, Rundown applications remain simple for smaller projects while retaining a clear upgrade path for larger systems.

Related Documents

• 12-system-architecture.md

• 13-architecture-boundaries.md

• 16-database-architecture.md

• 19-api-architecture.md

Related ADRs

• ADR-001: Repository Structure