Liwan

Liwan is a lightweight, privacy‑first web analytics platform built in Rust that delivers real‑time insights without the baggage of traditional tracking stacks. From a developer’s standpoint, it offers a single, self‑contained binary that eliminates database migrations, ORM layers, and external services. The core telemetry is captured via a minimal 1 KB JavaScript snippet that can be embedded on any page, sending HTTP POST requests directly to the Liwan server. Because all data is stored locally and no cookies or persistent identifiers are used, developers can deploy Liwan in compliance‑heavy environments such as GDPR‑strict sites or internal dashboards without additional configuration.

Liwan’s architecture is intentionally minimalistic yet highly scalable. The server is a Rust application compiled with cargo build --release, leveraging the asynchronous runtime tokio for non‑blocking I/O. Data ingestion is handled by a lightweight HTTP endpoint that accepts JSON payloads; the server parses these requests, normalizes fields (e.g., user agent, referrer), and writes the resulting records to a SQLite database by default. For high‑traffic deployments, the same binary can be paired with an external PostgreSQL or MySQL instance via a simple configuration flag, allowing horizontal scaling through read replicas. The dashboard is served from the same binary as a static asset bundle, with real‑time updates pushed via Server‑Sent Events (SSE) or WebSockets—ensuring that UI latency stays below 200 ms even under load.

• Bot & crawler filtering: Built‑in heuristics detect common bots (e.g., Googlebot, Bingbot) and exclude them from metrics.
• Referrer & campaign parsing: Liwan automatically parses UTM parameters and referrer headers, exposing them in the API for downstream analytics pipelines.
• Custom event tracking: Developers can send arbitrary events (e.g., button clicks, form submissions) through the same POST endpoint; these are stored alongside page view data and can be queried via a simple REST API.
• Export & ingestion: A JSON‑based export endpoint allows migration to other BI tools; conversely, an optional webhook can forward events to external services such as Grafana or Prometheus.
• SaaS‑ready API: The same HTTP endpoints used by the front‑end can be consumed programmatically, enabling integration with CI/CD dashboards or custom monitoring tools.

Liwan is designed for self‑hosting on commodity hardware. A single binary can run on a 1 GHz Raspberry Pi or a 2‑core VPS, thanks to Rust’s zero‑cost abstractions and tokio’s efficient event loop. Docker images are available on GitHub Container Registry (ghcr.io/explodingcamera/liwan:edge), simplifying containerized deployments. For environments requiring high availability, a reverse proxy (NGINX or Caddy) can be used to provide HTTPS termination and load balancing across multiple Liwan instances. The optional database switch to PostgreSQL allows horizontal scaling; the application supports connection pooling and read‑only replicas without code changes.

While Liwan ships with a ready‑to‑use dashboard, its open‑source nature invites extension. The API surface is intentionally minimal but fully documented in the repository’s docs/ folder, making it trivial to build custom widgets or export pipelines. A plugin architecture is planned for future releases: developers can write Rust crates that hook into the request‑processing pipeline, adding new event types or enriching data with external services (e.g., GeoIP lookups). Webhooks can be configured per project, enabling instant notifications to Slack, Discord, or custom microservices whenever traffic thresholds are crossed.

The project’s documentation follows a clear, example‑driven style. The README outlines all command‑line flags (--db, --port, --tls-cert), while the config/ directory contains a JSON schema for advanced users. Community support is active on GitHub Discussions, where contributors discuss feature requests and bug fixes. Licensing under Apache‑2.0 removes friction for commercial use, allowing developers to ship Liwan as part of a product without licensing headaches.

1. Privacy‑conscious websites: Blogs or portfolio sites that want analytics without tracking cookies.
2. Internal dashboards: Enterprise intranets where data must remain on-premises for compliance.
3. Edge deployments: Running Liwan on a CDN edge node to capture traffic closer to the source.
4. Custom monitoring: Integrating Liwan events into Prometheus/Grafana stacks for real‑time alerts.

• Performance: Rust’s safety and speed mean sub‑millisecond request handling, even on low‑end hardware.
• Simplicity: A single binary eliminates dependency hell and reduces attack surface.
• Privacy‑first out of the box: No cookies, no third‑party tracking—ideal for GDPR/FCC compliance.
• Extensibility: Open source with a clear API, ready for custom event pipelines or plugin development.
• Cost‑effective: Runs comfortably on a Raspberry Pi, lowering hosting costs compared to SaaS analytics platforms.

Liwan offers developers a powerful, low‑overhead alternative to commercial analytics solutions—combining Rust’s performance with an architecture that prioritizes privacy and simplicity.