Usertour

Usertour is an open‑source, self‑hosted platform that delivers in‑app product tours, checklists, launchers, and surveys. From a developer’s perspective it functions as a runtime SDK that can be dropped into any web application—whether single‑page or multi‑page—and a backend service that manages flow definitions, targeting rules, analytics, and user state. The SDK exposes a lightweight JavaScript API (usertour.start(), usertour.trackEvent(), etc.) that communicates with a REST/GraphQL API hosted by the server. This separation allows teams to iterate on flow designs in a visual editor while keeping all runtime logic on the client, reducing server load and enabling offline resilience.

• Front‑end SDK: Written in TypeScript, bundled with Rollup, and distributed as a single ES module. It renders flows using the HTML5 Canvas API for high‑performance overlays and supports progressive enhancement on older browsers.
• Back‑end Service: A Node.js application built with Express and Prisma ORM, exposing a GraphQL API for CRUD operations on flows, segments, and analytics. The service uses PostgreSQL as the primary data store, with optional Redis for caching user session state and targeting evaluation.
• Database Layer: PostgreSQL holds flow definitions, user attributes, event logs, and segmentation rules. Prisma’s schema‑first approach ensures type safety across the stack.
• Containerization: The entire stack is packaged in a Docker Compose file, exposing ports 8011 (frontend UI) and 8012 (API). The Compose file pulls images from Docker Hub (usertour/frontend, usertour/backend) and uses environment variables for configuration.
• Observability: Integrated with OpenTelemetry, the service emits metrics to Prometheus and traces to Jaeger, allowing developers to monitor flow execution latency and error rates.

Usertour is designed to run in any Docker‑capable environment, from a single VM to Kubernetes clusters. The docker-compose.yml defines two services; scaling can be achieved by deploying multiple replicas of the backend behind a load balancer and sharing PostgreSQL via a managed instance. For high‑availability, the database can be configured with streaming replication and connection pooling (PgBouncer). The lightweight SDK allows it to run on the client with minimal bandwidth, making it suitable for edge deployments and CDN‑cached assets.

• SDK Hooks: Developers can inject custom logic before a step renders (usertour.on('stepRender', callback)) or after an event fires.
• Webhooks: Configure outbound POSTs to external analytics or CRM systems when a user completes a flow.
• Plugin System: Custom steps can be added by publishing a plugin that registers a new component type; the backend loads plugins from a designated directory at startup.
• API: Full CRUD via GraphQL; pagination, filtering, and subscription support for real‑time updates.
• Third‑Party Auth: Supports OAuth2, SAML, and custom JWT authentication for enterprise integrations.

The project follows semantic versioning and maintains comprehensive documentation on docs.usertour.io. The codebase is modular, with clear separation of concerns, making contribution straightforward. TypeScript typings are provided for both the SDK and backend APIs, enabling IDE autocomplete and static type checks. The community is active on Discord and GitHub Discussions, with a dedicated channel for integration questions. Licensing under MIT ensures no cost barriers or restrictive obligations.

1. Product Onboarding – New users receive a guided tour that highlights key features, reducing churn.
2. Feature Rollouts – Targeted segments can be exposed to beta features with in‑app prompts.
3. User Feedback Loops – Inline surveys or checklists gather qualitative data without leaving the app.
4. Compliance Training – Mandatory onboarding flows for regulated industries can be enforced and tracked.

• Performance: Client‑side rendering keeps server load low; WebSocket batching reduces network overhead.
• Flexibility: Full control over flow JSON allows developers to integrate with existing state managers (Redux, Vuex) or server‑side rendering frameworks.
• Scalability: Stateless SDKs and a horizontally scalable backend make it easy to handle millions of concurrent users.
• Open‑Source Freedom: No vendor lock‑in, full access to source code for custom extensions or compliance audits.
• Rapid Iteration: