# evoluhq/evolu architecture

> Architecture diagram of the GitHub repository evoluhq/evolu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evoluhq/evolu
- Repository: https://github.com/evoluhq/evolu

## Overview

This Evolu monorepo is a modern, local-first platform that enables offline-first applications using technologies such as SQLite (across browsers, Electron, and React Native), CRDT for conflict-free merging, and end-to-end encrypted synchronization/backup. The project is structured as a monorepo containing multiple "apps" (native, server, and web), along with “packages” that encapsulate reusable libraries and shared logic (e.g., evolu-common, evolu-react-native, evolu-server, and evolu-react). It also provides “examples” demonstrating integrations with frameworks like Next.js, Remix, Electron, and Vite.

##### Main components
- Apps – The user-facing applications are in the “apps” folder and include:
- Native app: a React Native-based mobile application.
- Server app: a backend service (with Docker, fly.toml, etc.) that likely handles syncing and backups.
- Web app: a Next.js-based application for browser usage.
- Packages – Modular libraries that implement core functionality, including:
- evolu-common: Implements database, CRDT, diffing, crypto, and synchronization logic.
- evolu-react-native & evolu-react: Integrate Evolu’s core functionality with specific front-end frameworks.
- evolu-server: Provides server-specific logic, possibly including API endpoints and sync management.
- Examples – Demonstration projects showcasing Evolu’s integration in various environments (React Electron, Remix, etc.).
- Infrastructure & CI/CD – Configuration files and scripts (GitHub workflows, Dockerfiles, Changesets, etc.) that support building, linting, testing, and deployment.

##### Relationships and interactions
- Local-first Application Interaction: Each client application (native, web, and examples) uses the corresponding Evolu React or Evolu React Native package along with evolu-common to manage local SQLite databases, reactive queries, and CRDT-based sync.
- Synchronization Flow: The local client state is merged via the new sync protocol and eventually communicates with the Evolu server, which uses the evolu-server package to manage synchronization, backup, and serve as the central point for data reconciliation (even though the architecture promotes local data ownership).
- Package Dependencies: The reusable packages form the backbone of the functionality. They provide core interfaces for the apps, used across different platforms to enable consistent behavior (e.g., typed schemas, reactive queries, SQL abstraction using Kysely, etc.).
- Development Infrastructure: The monorepo uses pnpm for dependency management, with CI/CD workflows (GitHub workflows, Docker build configurations, etc.) ensuring consistent build and deployment processes across all packages and apps.

##### Architectural patterns and design principles
- Monorepo Organization: Emphasize the separation of concerns by organizing apps, packages, and examples in distinct directories.
- Local-first Design: Illustrate the principle of data ownership on the client side with local SQLite databases and synchronization mechanisms that work even in unreliable network conditions.
- Reactive and Typed Data Flow: Note the use of fully typed interfaces (leveraging TypeScript, branded types, and typed SQL via Kysely), and reactive queries that also support features like React Suspense.

##### Elements
- Use clear labels for every component:
- “Native App (React Native)”
- “Web App (Next.js)”
- “Server App”
- “Core Library Packages (evolu-common, evolu-react-native, evolu-react, evolu-server)”
- “Synchronization Service / Protocol”
- “SQLite Storage on Client”
- “CI/CD Infrastructure”
- Data flow from the UI components to local storage.
- Synchronization flow from the client to the server.
- Dependencies from the apps to the libraries in the packages folder.
- Integration with external workflows (Docker, GitHub CI/CD) for deployment and testing.
- Applications (e.g., rounded rectangles for client apps).
- Infrastructure components (e.g., gears, clouds).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Applications
    subgraph "Client Applications"
        NApp("Native App (React Native)"):::app
        WApp("Web App (Next.js)"):::app
        SQLite("SQLite Storage on Client"):::db
    end

    %% Core Library Packages
    subgraph "Core Library Packages"
        ECommon("evolu-common\n(core: database, CRDT, sync)"):::pkg
        EReactNative("evolu-react-native"):::pkg
        EReact("evolu-react"):::pkg
        EServer("evolu-server"):::pkg
        Sync("Synchronization Service/Protocol"):::sync
    end

    %% Backend Services
    subgraph "Backend Services"
        SApp("Server App"):::server
    end

    %% CI/CD Infrastructure
    subgraph "CI/CD Infrastructure"
        CI("CI/CD (GitHub Workflows, Docker, Build Scripts)"):::infra
    end

    %% Relationships between Clients and Packages
    NApp -->|"uses"| EReactNative
    NApp -->|"uses"| ECommon
    WApp -->|"uses"| EReact
    WApp -->|"uses"| ECommon

    %% Local Storage connection
    NApp -->|"storesDataIn"| SQLite

    %% Synchronization Flow
    ECommon -->|"includes"| Sync
    NApp -->|"syncsVia"| Sync
    WApp -->|"syncsVia"| Sync

    %% Server synchronization and package integration
    Sync -->|"syncsWith"| SApp
    SApp -->|"handlesSyncVia"| EServer
    SApp -->|"integratesWith"| ECommon

    %% CI/CD building and testing all components
    CI -->|"buildsTests"| NApp
    CI -->|"buildsTests"| WApp
    CI -->|"buildsTests"| SApp
    CI -->|"buildsTests"| ECommon
    CI -->|"buildsTests"| EReactNative
    CI -->|"buildsTests"| EReact
    CI -->|"buildsTests"| EServer

    %% Click Events
    click NApp "https://github.com/evoluhq/evolu/tree/main/apps/native/"
    click WApp "https://github.com/evoluhq/evolu/tree/main/apps/web/"
    click SApp "https://github.com/evoluhq/evolu/tree/main/apps/server/"
    click ECommon "https://github.com/evoluhq/evolu/tree/main/packages/evolu-common/"
    click EReactNative "https://github.com/evoluhq/evolu/tree/main/packages/evolu-react-native/"
    click EReact "https://github.com/evoluhq/evolu/tree/main/packages/evolu-react/"
    click EServer "https://github.com/evoluhq/evolu/tree/main/packages/evolu-server/"
    click SQLite "https://github.com/evoluhq/evolu/tree/main/apps/native/src/db/"
    click Sync "https://github.com/evoluhq/evolu/blob/main/packages/evolu-common/src/Sync.ts"
    click CI "https://github.com/evoluhq/evolu/tree/main/.github/"

    %% Styles
    classDef app fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef pkg fill:#aed6f1,stroke:#1b4f72,stroke-width:2px;
    classDef db fill:#d2b4de,stroke:#6c3483,stroke-width:2px;
    classDef server fill:#f5b7b1,stroke:#943126,stroke-width:2px;
    classDef infra fill:#d5f5e3,stroke:#117864,stroke-width:2px;
    classDef sync fill:#fadbd8,stroke:#943126,stroke-width:2px;
```
