Architecture Overview
This library provides a robust framework for building offline-first web applications, prioritizing seamless data synchronization and a structured approach to task management. Developers interact with its core logic primarily through the KaamSync Core, which orchestrates the application's React Router setup for client and server-side rendering. Key entry points include app/root.tsx and app/entry.server.tsx, guiding the application's lifecycle. The core value proposition lies in its offline-first capabilities, powered by an underlying synchronization engine.
Under the hood, the KaamSync architecture is driven by a sophisticated Route Matching and Rendering Engine, responsible for translating URL paths into specific UI components and managing server-side logic. This engine works in concert with the Data Fetching and Mutation Service, which acts as the primary interface to the Zero Sync Engine. This service handles all data operations, translating application requests into commands for Zero, ensuring data is always available and consistent, even without a network connection. The Zero Sync Engine itself is a critical component, managing local data storage and synchronization across devices and servers, underpinning the application's offline-first promise.
The application's structure is further defined by the React Router Configuration, which dictates how routes are discovered and processed, including settings for server-side rendering and advanced routing features. Data persistence is managed through the Database Schema Definitions, which outline the structure of the PostgreSQL database using Drizzle ORM. This provides a type-safe way to interact with data, ensuring integrity and enabling powerful querying. For security, the Authentication API Gateway centralizes and secures all user authentication flows, integrating with the 'better-auth' library to manage sign-up, login, and session management.
To facilitate rapid and consistent UI development, the library offers a collection of UI Components. These reusable elements, built with libraries like Radix UI and styled with Tailwind CSS, abstract common interface patterns, allowing developers to focus on application logic. These components are readily available and can be composed to build rich user interfaces.
This architecture is designed to provide a flexible yet opinionated foundation for applications requiring reliable offline functionality. The separation of concerns, from routing and data synchronization to UI presentation, allows for maintainable and scalable development. The intentional design choices around data handling and synchronization, powered by the Zero Sync Engine, are central to its value proposition.
For contributors looking to engage with the codebase, understanding the KaamSync Core is a good starting point, as it acts as the application's central orchestrator. Familiarize yourself with how the Route Matching and Rendering Engine interacts with the Data Fetching and Mutation Service. Examining the UI Components will provide insight into the presentational layer. The interconnectedness of these major pieces forms the backbone of the KaamSync framework, and grasping these relationships will be crucial for making effective contributions.