Merge pull request #15 from sidequery/readme-positioning

Improve README positioning

Author: nicosuave

README.md

@@ -2,18 +2,34 @@
 
 <img src="hog.png" alt="Hogflare" width="220">
 
-Hogflare is a Cloudflare Workers ingestion layer for PostHog SDKs. It supports PostHog-style ingestion, stateful persons and groups, SDK feature flags, and a read-only session replay explorer, then streams events and person snapshots into Cloudflare Pipelines so data lands in R2 as Iceberg/Parquet.
+Hogflare is a warehouse-native PostHog alternative that runs on Cloudflare. Point existing PostHog SDKs at a Worker to capture events, resolve persons and groups, evaluate feature flags, ingest session replay, and write queryable product analytics data to R2 Data Catalog Iceberg tables.
+
+It is built for teams that want PostHog-compatible analytics primitives in their own Cloudflare lakehouse, without operating the full PostHog stack.
 
 ![Hogflare replay explorer](docs/assets/replay-explorer.jpg)
 
-## What Works Today
+## Product Surface
+
+- PostHog-compatible SDK endpoints: `/capture`, `/identify`, `/alias`, `/batch`, `/e`, `/engage`, `/groups`, `/s`
+- Stateful persons and groups: `$set`, `$set_once`, `$unset`, aliasing, group properties, group slots, and append-only person snapshots
+- Feature flags and remote config: `/array/:token/config`, `/flags`, and `/decide`
+- Session replay: PostHog replay ingestion plus an R2 SQL-backed explorer for sessions, event search, funnels, friction signals, and person journeys
+- Warehouse output: event rows and person snapshots in R2 Data Catalog-backed Iceberg/Parquet tables
+- Cloudflare-native enrichment: IP, geo, colo, ASN, and related request metadata
+- Backfill importer for existing PostHog persons, groups, and historical events
+
+## Semantic Model
+
+Hogflare includes semantic model definitions over the R2/Iceberg tables so teams can query product analytics directly from DuckDB, R2 SQL, or BI tooling:
+
+- Core facts: `events`, `sessions`, `pageviews`, `activity_days`
+- Identity and profiles: `persons`, `person_profiles`, `identity_links`
+- Product analytics: `first_event_retention`, `attribution`, `groups`
+- Reusable metrics: identification rate, pageviews per session, events per user, grouped event rate, day 1/7/30 retention, bounce rate, engagement rate, attribution rate, and identity links per profile
+
+## What It Is Not Yet
 
-- PostHog-compatible ingestion endpoints: `/capture`, `/identify`, `/alias`, `/batch`, `/e`, `/engage`, `/groups`, `/s`
-- Persons and groups: `$set`, `$set_once`, `$unset`, aliasing, group properties, and group slots
-- SDK config and feature flags: `/array/:token/config`, `/flags`, and `/decide`
-- Session replay ingestion and read-only replay explorer backed by R2 SQL over Iceberg rows
-- Request enrichment with Cloudflare IP and geo fields
-- Queryable event and person snapshots in R2 Data Catalog-backed Iceberg tables
+Hogflare is not a full PostHog clone. It does not try to ship PostHog's complete app surface, plugin system, cohort engine, or ClickHouse-backed query layer. The focus is PostHog SDK compatibility, product analytics data ownership, replay review, and a practical semantic layer on Cloudflare-managed storage.
 
 ## Docs
 
@@ -22,15 +38,19 @@ Hogflare is a Cloudflare Workers ingestion layer for PostHog SDKs. It supports P
 - [PostHog Compatibility](docs/posthog-compatibility.md): SDK setup, endpoint behavior, persons, groups, feature flags, signing, and enrichment.
 - [Import Existing PostHog Data](docs/import-posthog.md): host-side backfill importer for existing PostHog projects.
 - [Data Model](docs/data-model.md): event and person row shapes plus DuckDB/R2 SQL query examples.
+- [`models/`](models): semantic model definitions for events, sessions, pageviews, persons, identity, groups, attribution, retention, and shared metrics.
 
 ## Architecture
 
 ```mermaid
 flowchart TB
     SDKs["PostHog SDKs"]
+    Importer["PostHog Importer"]
 
     SDKs -->|"ingest"| Worker
     SDKs -->|"flags/decide"| Worker
+    Importer -->|"backfill"| EventsPipeline
+    Importer -->|"person snapshots"| PersonsPipeline
 
     subgraph CF["Cloudflare Workers"]
         Worker["Hogflare Worker"]
@@ -52,19 +72,22 @@ flowchart TB
     PersonsPipeline --> PersonsR2["R2 Data Catalog<br/>persons table"]
 
     ReplayUI["Replay Explorer"] -->|"R2 SQL"| EventsR2
+    Models["Semantic Models<br/>models/*.yml"] --> EventsR2
+    Models --> PersonsR2
+    Consumers["DuckDB / R2 SQL / BI"] --> Models
 ```
 
 ## Why
 
-PostHog is a nice-to-use web and product analytics platform. Self-hosting PostHog is prohibitively complex, so most users rely on the cloud offering. Hogflare is an alternative for cost-conscious data teams and businesses that want a low-maintenance way to ingest web and product analytics directly into a managed data lake.
+PostHog is a nice-to-use web and product analytics platform. Self-hosting PostHog is prohibitively complex, so most users rely on the cloud offering. Hogflare is for cost-conscious data teams and businesses that want product analytics, session replay, feature flags, identity resolution, and modeled warehouse data in infrastructure they control.
 
 A [hobby deployment of PostHog](https://github.com/PostHog/posthog/blob/master/docker-compose.hobby.yml) includes postgres, redis, redis7, clickhouse, zookeeper, kafka, worker, web, plugins, proxy, objectstorage, seaweedfs, asyncmigrationscheck, temporal, elasticsearch, temporal-admin-tools, temporal-ui, temporal-django-worker, cyclotron-janitor, capture, replay-capture, property-defs-rs, livestream, feature-flags, and cymbal.
 
-PostHog does much more than this package, but some teams only need the warehouse-first basics.
+PostHog does much more than Hogflare, but many teams do not need to run PostHog's entire application stack to get useful web and product analytics. Hogflare keeps the SDK integration familiar while making Cloudflare Pipelines, R2 Data Catalog, and Iceberg the system of record.
 
-## Replay Demo
+## Local Replay Demo
 
-The branch includes a local replay fixture that makes the explorer usable without Cloudflare credentials:
+The repo includes a local replay fixture that makes the explorer usable without Cloudflare credentials:
 
 ```bash
 REPLAY_DEMO_PORT=4666 bun scripts/replay_demo_stub.mjs