Smart Questionnaire

Architecture & Infrastructure

The platform is a TypeScript monorepo (pnpm + Turborepo) with three applications and one shared type package. A key architectural decision was `@smartq/shared`: enums, DTOs, and domain types are defined once and imported into the backend and both frontends, so the compiler guarantees that client and server always stay in sync. The backend is a modular NestJS service (18 modules) with data isolated per organization (multi-tenant) and a versioned REST API featuring global validation, structured logging, and correlation IDs. At the infrastructure level, the system runs on a k3s cluster behind an HA network with HAProxy and three edge/ingress nodes, distributing traffic from a large number of devices evenly and keeping the system available even when a single node fails. Access to the server and internal services is secured over a private Tailscale network.

Platform Ecosystem

• Admin / Authoring Panel: A React-based web application for building conditional, branching questionnaires and exercising full control over devices, locations, media, database, and logs.
• API Layer: The central NestJS service handling business logic, authentication, synchronization, data export, and media processing.
• Mobile Field Application: An Expo / React Native app for device enrollment, offline questionnaire completion, and reliable synchronization.
• Shared Type Layer: '@smartq/shared` — a single source of truth defining the contract shared across all applications.
• AI Module (SmartQAI): An assistant for questionnaire design and support, with a pluggable LLM provider.
• Infrastructure: PostgreSQL, MinIO, k3s, HAProxy, Tailscale, Traefik, and Docker.

The Challenge

rands needed a way to systematically collect high-quality brand data from a large number of points of sale and devices — a task that combines several hard problems at once. Questionnaires are complex and branch based on answers, with photos and video attached. Surveyors often work without a network connection, so data must be cached locally and synchronized later without loss and without duplicates. The biggest engineering challenge was deployment and scaling: providing stable, reliable access for a large number of devices that simultaneously pull synchronization and send metrics — all with full operational control and security.

 

The Solution

We built a single platform around a visual questionnaire editor, where branching is modeled as a graph with validation of invalid routes, paired with an offline-first mobile app whose synchronization is idempotent — a mutex and a unique index on `clientSubmissionId` at the database level guarantee there are no duplicates even under repeated syncs. The admin panel provides full operational control over the fleet: device locations on a map, remote commands (force-sync, pulling responses, logs), media, and database. To withstand scale, the system was deployed on a k3s cluster behind an HA network with HAProxy and three edge/ingress nodes, containerized and securely networked over Tailscale. Security is production-grade: JWT with refresh tokens, MFA/TOTP, RBAC with five roles, CSRF protection, and rate-limiting.

The Result

A complete, production-ready system built from scratch and running at real scale. SmartData Belgrade now operates on infrastructure that has proven itself under load:

• Over 500 active devices in the field
• 200–300 field surveyors
• 99% uptime, enabled by the HA network with HAProxy and a k3s cluster with three edge/ingress nodes
• Over 3,000,000 registered locations
• Over 50,000,000 data points collected