lytics

## Overview Lytics is a self‑hosted web analytics suite focused on user privacy. It offers standard traffic metrics, custom SQL‑based queries, and visual heatmaps that show user interaction on pages. The project is split into several modules: - **lytics-ping** – lightweight HTTP endpoint that receives tracking data from the JavaScript tag. - **lytics-app** – the main Quarkus service that stores data, generates reports, and serves the UI. - **lytics-query** – validates and transpiles SQL queries used by reports and heatmaps. - **tag** – a small JavaScript snippet that website owners embed to send events to the ping service. - **offsite** – JavaScript and rendering logic for heatmaps that are loaded from a separate domain. - **schemas** – database schema definitions for MariaDB/MySQL and ClickHouse. ## Architecture The platform stores raw events in ClickHouse for high‑performance analytics while relational metadata lives in MariaDB/MySQL. The Quarkus‑based services communicate via HTTP and share configuration through `application.properties`. Heatmap rendering is performed client‑side using the off‑site script, which is built with npm and served as a static asset by the Quarkus server. ## Getting Started 1. **Database setup** – provision a MariaDB/MySQL instance and a ClickHouse cluster. Apply the schemas from the `schemas` directory. 2. **Configuration** – edit `lytics-app/src/main/resources/application.properties` with connection strings and any desired options. 3. **Build** – run `mvn package` to compile all modules. 4. **Run services**: ```bash java -Dquarkus.config.locations=application.properties -jar lytics-ping/target/lytics-ping-1.0.0-SNAPSHOT-runner.jar java -Dquarkus.config.locations=application.properties -jar lytics-app/target/lytics-app-1.0.0-SNAPSHOT-runner.jar ``` 5. **Development** – use the Quarkus plugin in IntelliJ or `quarkus dev` from the command line. For heatmap script changes, run `npm run watch` inside the `offsite` directory; the output is placed in `lytics-app/src/main/resources/web/static/offsite/offsite.min.js`. ## Troubleshooting If you encounter dependency resolution issues or IDE problems, a clean reinstall can help: ```bash mvn clean install -U ``` ## Use Cases - Privacy‑compliant visitor tracking for websites that cannot use third‑party analytics. - Visual heatmaps to understand click and scroll behavior without compromising user data. - Customizable SQL queries for advanced reporting and data export. Lytics provides a full stack for organizations that need on‑premise analytics with fine‑grained control over data storage and processing.