# atoms-studio/nuxt-swiftsearch architecture

> Architecture diagram of the GitHub repository atoms-studio/nuxt-swiftsearch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atoms-studio/nuxt-swiftsearch
- Repository: https://github.com/atoms-studio/nuxt-swiftsearch

## Overview

##### Project type and purpose
- This is an open-source Nuxt 3 module/package (“@atoms-studio/nuxt-swiftsearch”) that provides a tailored implementation of Algolia InstantSearch for Nuxt 3 apps.
- It ships with three “sub-projects”:
- src/ – the core module code (module entrypoint, runtime Vue components, composables, utils)
- docs/ – a Nuxt 3 site hosting documentation and example API routes
- playground/ – a Nuxt 3 app demonstrating usage

##### File structure
- Top level: module entry (src/module.ts), runtime subfolder (components, composables, utils), tests, docs, playground.
- docs/ and playground/ are standalone Nuxt 3 applications: each has its own nuxt.config.ts, pages/, components/, server/api/, package.json.
- src/runtime/components – all <ais-*> Vue components.
- src/runtime/composables – hooks like useInstantSearch(), useAisHits(), etc.
- test/ – Vitest unit tests and fixtures.

##### Extract insights from the README
- SSR-first, client-on-demand.
- Centralized reactive search state via Vue composables.
- 99% compatibility with vue-instantsearch.
- Typed components courtesy of TypeScript.

##### Elements
- Module installation → plugin registration
- Component → composable calls
- Composables → Algolia API requests
- SSR data-flow vs. client-side flow
- Green for consumer apps (docs, playground, user apps)
- Orange for external services (Algolia API)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer Apps
    subgraph "Consumer Nuxt Apps" 
        direction TB
        Docs["Documentation Site"]:::consumer
        Playground["Playground Demo"]:::consumer
        subgraph "Docs App Details"
            direction TB
            DocsAPI["Server API Example"]:::consumer
            DocsTailwind["Tailwind Config"]:::consumer
            DocsBunLock["bun.lockb"]:::consumer
            DocsPnpmLock["pnpm-lock.yaml"]:::consumer
        end
        subgraph "Playground App Details"
            direction TB
            PlaygroundAPI["Server API Example"]:::consumer
            PlaygroundComposables["Custom Composables"]:::consumer
            PlaygroundBunLock["bun.lockb"]:::consumer
        end
    end

    %% Module Loader
    ModuleLoader["Nuxt Module Loader"]:::core
    RuntimePlugin["Runtime Plugin"]:::core

    %% Runtime internals
    subgraph "Runtime Module Code" 
        direction TB
        Components["Vue Components (Ais Widgets)"]:::core
        Composables["Composables (Search Hooks & State)"]:::core
        Utils["Utility Functions"]:::core
    end

    %% Data Flow Layers
    SSR["SSR Layer"]:::layer
    Client["Client Layer"]:::layer

    %% External services
    AlgoliaClient["Algolia InstantSearch JS Client"]:::external
    AlgoliaAPI["Algolia Search API"]:::external

    %% Tests & CI
    subgraph "Tests & CI" 
        direction TB
        Tests["Unit Tests & Fixtures"]:::ci
        VitestConfig["Vitest Config"]:::ci
        TSConfig["TypeScript Config"]:::ci
        ESLintConfig["Prettier/ESLint Config"]:::ci
        PackageJSON["package.json"]:::ci
        Lockfiles["Lockfiles"]:::ci
    end

    %% Connections
    Docs -->|uses| ModuleLoader
    Playground -->|uses| ModuleLoader

    ModuleLoader -->|install module| RuntimePlugin
    RuntimePlugin -->|register| Components
    RuntimePlugin -->|register| Composables
    RuntimePlugin -->|register| Utils

    Components -->|call/read/write state| Composables
    Composables -->|instantiate/configure| AlgoliaClient
    AlgoliaClient -->|send queries| AlgoliaAPI

    SSR -->|initial search| Composables
    Composables -->|serialize results| SSR
    Client -->|hydrate/reuse state| Composables
    Client -->|on-demand search| Composables

    Tests -.-> ModuleLoader
    Tests -.-> RuntimePlugin
    Tests -.-> Components
    Tests -.-> Composables

    %% Click Events
    click Docs "https://github.com/atoms-studio/nuxt-swiftsearch/tree/main/docs/"
    click Playground "https://github.com/atoms-studio/nuxt-swiftsearch/tree/main/playground/"
    click ModuleLoader "https://github.com/atoms-studio/nuxt-swiftsearch/blob/main/src/module.ts"
    click RuntimePlugin "https://github.com/atoms-studio/nuxt-swiftsearch/tree/main/src/runtime/"
    click Components "https://github.com/atoms-studio/nuxt-swiftsearch/tree/main/src/runtime/components/"
    click Composables "https://github.com/atoms-studio/nuxt-swiftsearch/tree/main/src/runtime/composables/"
    click Utils "https://github.com/atoms-studio/nuxt-swiftsearch/tree/main/src/runtime/utils/"
    click Tests "https://github.com/atoms-studio/nuxt-swiftsearch/tree/main/test/"
    click VitestConfig "https://github.com/atoms-studio/nuxt-swiftsearch/blob/main/vitest.config.ts"
    click TSConfig "https://github.com/atoms-studio/nuxt-swiftsearch/blob/main/tsconfig.json"
    click ESLintConfig "https://github.com/atoms-studio/nuxt-swiftsearch/blob/main/.eslintrc"
    click PackageJSON "https://github.com/atoms-studio/nuxt-swiftsearch/blob/main/package.json"
    click Lockfiles "https://github.com/atoms-studio/nuxt-swiftsearch/blob/main/bun.lockb"
    click DocsAPI "https://github.com/atoms-studio/nuxt-swiftsearch/blob/main/docs/server/api/search.json.get.ts"
    click DocsTailwind "https://github.com/atoms-studio/nuxt-swiftsearch/blob/main/docs/tailwind.config.ts"
    click DocsBunLock "https://github.com/atoms-studio/nuxt-swiftsearch/blob/main/docs/bun.lockb"
    click DocsPnpmLock "https://github.com/atoms-studio/nuxt-swiftsearch/blob/main/docs/pnpm-lock.yaml"
    click PlaygroundAPI "https://github.com/atoms-studio/nuxt-swiftsearch/blob/main/playground/server/api/testApi.ts"
    click PlaygroundComposables "https://github.com/atoms-studio/nuxt-swiftsearch/tree/main/playground/composables/"
    click PlaygroundBunLock "https://github.com/atoms-studio/nuxt-swiftsearch/blob/main/playground/bun.lockb"

    %% Styles
    classDef consumer fill:#d4f7d4,stroke:#2d7a2d,color:#000
    classDef core fill:#cde7f0,stroke:#2b5c6b,color:#000
    classDef layer fill:#f0e2c9,stroke:#a17b38,color:#000
    classDef external fill:#f4c8c8,stroke:#a12b2b,color:#000
    classDef ci stroke-dasharray: 5 5,fill:#ffffff,stroke:#999,color:#000
```
