algolia-reference-architecture

name	algolia-reference-architecture
description	Implement Algolia reference architecture: index design, multi-index strategy, data pipeline, search service layer, and frontend/backend separation. Trigger: "algolia architecture", "algolia best practices", "algolia project structure", "how to organize algolia", "algolia index design".
allowed-tools	Read, Grep
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","search","algolia"]
compatibility	Designed for Claude Code

Algolia Reference Architecture

Overview

Production-ready architecture for Algolia-powered search. Covers index design, data pipeline from source to Algolia, service layer patterns, and frontend integration.

Prerequisites

• A source-of-truth datastore, an approved transformation boundary, and explicit ownership for indexing and search-serving services.
• Separate Admin and search-only credentials, kept on the backend and frontend respectively.
• An environment and index naming convention that permits safe rehearsal and rollback.

Instructions

Use the architecture, project layout, and design patterns as a composable reference. Keep indexing, settings management, and search serving as separately testable boundaries rather than coupling them to a frontend component.

Examples

The diagrams and TypeScript patterns below demonstrate the reference topology, record transformation, settings-as-code, and service-layer contracts. Adapt the interfaces to your source schema while preserving the key boundary between write and search credentials.

Architecture Overview

┌──────────────────────────────────────────────────────────────┐
│                      Frontend                                 │
│  InstantSearch.js / React InstantSearch                       │
│  Uses: liteClient (search-only key)                          │
│  Sends: search-insights events (clicks, conversions)          │
└───────────────────────┬──────────────────────────────────────┘
                        │ Search + Events
                        ▼
┌──────────────────────────────────────────────────────────────┐
│                   Algolia Cloud                               │
│  ┌─────────┐  ┌──────────────┐  ┌─────────────┐             │
│  │ Search   │  │ Analytics    │  │ Recommend   │             │
│  │ Engine   │  │ + Insights   │  │ (ML-based)  │             │
│  └─────────┘  └──────────────┘  └─────────────┘             │
└───────────────────────▲──────────────────────────────────────┘
                        │ Indexing (admin key)
                        │
┌──────────────────────────────────────────────────────────────┐
│                    Backend Service                            │
│  ┌────────────┐  ┌──────────────┐  ┌─────────────────┐      │
│  │ Search     │  │ Indexing     │  │ Settings        │      │
│  │ Service    │  │ Pipeline     │  │ Manager         │      │
│  └────────────┘  └──────┬───────┘  └─────────────────┘      │
│                         │                                     │
│  ┌──────────────────────▼────────────────────────────┐       │
│  │              Source Database                        │       │
│  │  PostgreSQL / MongoDB / CMS / External API          │       │
│  └────────────────────────────────────────────────────┘       │
└──────────────────────────────────────────────────────────────┘

Project Structure