Architecture Overview

This section provides an overview of the Qlarr architecture and how different components interact.

System Design

Qlarr follows a modular architecture with clear separation of concerns:

Survey Engine (KMP)
- Parses survey definitions
- Generates state machines
- Manages survey execution
- Creates database schemas
Survey Engine Script
- JavaScript expression validation
- AST-based parsing
- Safety constraints enforcement
- Whitelisted function execution
Backend
- REST API endpoints
- Survey management
- Response caching
- Data synchronization
- PostgreSQL integration
Frontend
- WYSIWYG survey editor
- Survey rendering
- Administrative interface
- React-based UI
Android
- Native Android implementation
- iOS support (planned)

Everything revolves around two use cases: designing surveys and running surveys.

The Frontend provides a WYSIWYG editor for designing surveys
The survey definition is stored as a JSON file on the Backend
The Backend uses the Survey Engine to process the design — validating structure, generating the component graph, state machine files, and database schema for responses

The Frontend requests survey content from the Backend
The Backend uses the Survey Engine to navigate the survey — resolving which components to show, evaluating conditions, and managing state
Responses and survey settings are stored in PostgreSQL

The Android app downloads processed surveys from the Backend while online
The app includes its own copy of the Survey Engine (KMP native build), so it can run surveys fully offline
Responses are stored locally and synced back to the Backend when connectivity is available