How evoluhq/evolu works
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).