docs: add STATUS.md and MARKETING.md

STATUS.md — full project state, what's done, what's left, deployment checklist, key commands, architecture notes MARKETING.md — go-to-market plan with positioning, target audience, competitive analysis, 90-day content calendar, launch checklist, pricing strategy, metrics
2026-05-25 13:35:55 +03:00
parent ea68fa7767
commit 1a7189cc32
2 changed files with 547 additions and 0 deletions
@@ -0,0 +1,305 @@
 # Analytics Platform — Marketing Plan
 > Version 1.0 — 2026-05-25
 ---
 ## 1. Product Overview
 A self-hosted, privacy-focused web analytics platform. Users install a lightweight JavaScript snippet and get real-time dashboards, goal tracking, funnels, segments, alerts, and a full API — without sending visitor data to Google, Meta, or any third party.
 **Core value proposition:** The power of Google Analytics, with the privacy of Plausible, at a price that scales with your hosting costs rather than your traffic.
 ---
 ## 2. The Problem We Solve
 - **Privacy regulations** (GDPR, CCPA, ePrivacy) make GA4 legally risky in many markets — especially for EU-based businesses
 - **GA4 is genuinely hard to use** — it's built for enterprise advertisers, not product teams or indie developers
 - **Third-party SaaS analytics is expensive at scale** — Plausible, Fathom, and Mixpanel charge $9–$999/month based on pageviews or events
 - **Self-hosted alternatives are limited** — Umami and Matomo exist but lack goals, funnels, segments, and API access in their free tiers
 Our platform gives technical users a full-featured analytics stack they own and control, deployed on their own infrastructure.
 ---
 ## 3. Target Audience
 ### Primary — Indie Developers & Solo SaaS Founders
 - Building products and tired of paying per-pageview fees
 - Care about user privacy and GDPR compliance
 - Comfortable self-hosting on a $5–20/month VPS
 - Want real metrics: funnels, goals, conversion rates — not just pageviews
 - Often run multiple projects and want one analytics instance for all of them
 ### Secondary — Small Agencies (2–20 person)
 - Managing analytics for 5–50 client websites
 - Frustrated by the cost of per-site SaaS tools at scale
 - Want white-label or multi-tenant capability
 - Need API access to build client-facing dashboards or reports
 ### Tertiary — Privacy-Conscious Businesses
 - Companies under strict data residency requirements (EU, healthcare, finance)
 - Marketing teams that have been told to remove GA4 by legal
 - Businesses that have made privacy a public-facing value
 ### Who This Is NOT For (yet)
 - Large enterprises with dedicated analytics teams (need Snowflake, dbt, Looker)
 - Non-technical users who can't manage a server
 - Teams that need mobile app SDKs (web only for now)
 ---
 ## 4. Competitive Landscape
 | Product | Model | Price | Self-hosted | Goals/Funnels | API |
 |---|---|---|---|---|---|
 | **Google Analytics 4** | Free (you are the product) | Free | ❌ | ✅ | ✅ |
 | **Plausible** | SaaS | $9–$19+/mo | ✅ (paid) | Limited | ✅ |
 | **Fathom** | SaaS | $14+/mo | ❌ | Limited | ✅ |
 | **Matomo** | Open source / SaaS | Free self-hosted | ✅ | ✅ | ✅ |
 | **Umami** | Open source | Free self-hosted | ✅ | Limited | ✅ |
 | **Mixpanel** | SaaS | $0–$999+/mo | ❌ | ✅ | ✅ |
 | **Our Platform** | Open source | Free self-hosted | ✅ | ✅ Full | ✅ Full |
 ### Our Differentiators
 1. **Full feature set, free** — goals, funnels, segments, alerts, custom dashboards, annotations, API — all included, no paid tiers
 2. **One instance, unlimited websites** — no per-site pricing
 3. **Developer-first API** — pull any metric programmatically for dashboards or integrations
 4. **Laravel ecosystem** — easy for PHP/Laravel developers to customize, extend, and contribute
 5. **Truly self-hosted** — your data never leaves your server
 ---
 ## 5. Positioning Statement
 **For** indie developers, SaaS founders, and small agencies **who** are frustrated by the cost, complexity, or privacy implications of existing analytics tools, **our platform is** a self-hosted web analytics solution **that** gives them full-featured, GDPR-compliant analytics — goals, funnels, segments, and API access — deployed on their own infrastructure in under 10 minutes. **Unlike** Plausible or Fathom, **we** don't charge per pageview and don't hold your data.
 ---
 ## 6. Pricing Strategy
 The platform is **free and open source**. Revenue comes from value-added services:
 ### Tier 1 — Self-Hosted (Free, Open Source)
 - Full platform, unlimited websites, unlimited data
 - Community support (GitHub issues, Discord)
 - You manage hosting
 ### Tier 2 — Managed Hosting (Future — $9/mo)
 - We host it for you on our infrastructure
 - Automatic updates, backups, uptime monitoring
 - Email support
 - Positioned against Plausible/Fathom on price
 ### Tier 3 — Business Hosting (Future — $29/mo)
 - Managed hosting + priority support
 - Custom domain for tracker script (CDN included)
 - SLA, audit logs
 - Targeted at agencies managing client analytics
 ### Why Open Source First
 - Builds trust through transparency (critical for a privacy tool)
 - Community contributions improve the product faster
 - Developers try it free → recommend it → agencies pay for managed hosting
 - OSS projects in this space (Umami, Matomo) have strong long-term growth
 ---
 ## 7. Go-to-Market Strategy
 ### Phase 1 — Launch (Months 1–2)
 **Goal:** Get 500 GitHub stars and 100 self-hosted installs.
 **Channels:**
 - **Product Hunt launch** — Submit on a Tuesday morning (US time). Write a detailed maker story about why you built it. Reply to every comment within 24 hours.
 - **Hacker News Show HN** — Write a technical post explaining the architecture decisions (why Laravel, why self-hosted, how the aggregation pipeline works). Devs respect specifics.
 - **Reddit** — Post in r/selfhosted, r/privacy, r/webdev, r/Laravel, r/Entrepreneur. Be genuinely helpful, not promotional. Show the product solving a real problem.
 - **Dev.to / Hashnode article** — "I built a Google Analytics alternative in Laravel — here's how the data pipeline works." Technical depth attracts developers who will self-host and share.
 - **Twitter/X** — Share the launch, post screenshots of the dashboard, engage with #buildinpublic and #Laravel communities.
 **Launch content to prepare:**
 - A 90-second screen-recorded demo video (no voiceover, just the UI with captions)
 - A live demo instance at `demo.youranalytics.app` pre-seeded with realistic data
 - A 1-click deploy button for Railway, Render, or DigitalOcean App Platform
 - A `docker-compose.yml` so developers can run it in one command
 ---
 ### Phase 2 — Growth (Months 3–6)
 **Goal:** 2,000 GitHub stars, 500 active installs, 50 managed hosting customers.
 **SEO — Long-tail content strategy:**
 Write in-depth comparison articles and tutorials that rank for searches developers actually make:
 | Article Title | Target Keyword | Intent |
 |---|---|---|
 | "Google Analytics vs Self-Hosted: Why I Switched" | `self-hosted analytics` | Awareness |
 | "Plausible Alternative: Full-Featured and Free" | `plausible alternative` | Comparison |
 | "GDPR-Compliant Analytics Without Cookies" | `gdpr analytics no cookies` | Pain point |
 | "How to Self-Host Web Analytics on a $5 VPS" | `self host analytics` | How-to |
 | "Laravel Web Analytics — Building a Tracker from Scratch" | `laravel analytics` | Developer |
 | "Matomo vs [Our Platform]: Which Should You Use?" | `matomo alternative` | Comparison |
 | "How I Track Conversions Without Google" | `track conversions without google analytics` | Pain point |
 **Community building:**
 - Open a Discord server — #announcements, #support, #showcase, #dev
 - Monthly "what are you tracking?" thread on Discord/GitHub Discussions
 - Publish a public roadmap (GitHub Projects or Linear)
 - Recognize contributors on a CONTRIBUTORS page and in release notes
 **Developer relations:**
 - Publish an integration guide for major frameworks (Next.js, Nuxt, SvelteKit, WordPress)
 - Write an "extending the platform" post — how to add a custom report or data source
 - Offer a "built with" badge for developers using the platform on their sites
 ---
 ### Phase 3 — Monetization (Months 6–12)
 **Goal:** Launch managed hosting, reach $2,000 MRR.
 **Managed hosting launch sequence:**
 1. Announce to existing community first — offer 30-day free trial, no credit card
 2. Reach out personally to power users who have filed GitHub issues or starred the repo
 3. Product Hunt launch #2: "Managed hosting for [Platform] — your analytics, zero maintenance"
 4. Write a comparison post: "Self-hosting vs managed: what's the real cost of your time?"
 **Partnership opportunities:**
 - Approach Laravel Forge, Ploi, or Coolify about a one-click deploy integration
 - Reach out to Laravel News for a sponsored post or feature
 - Partner with privacy-focused hosting providers (Hetzner, Contabo, Greenhost) for joint content
 - Offer an affiliate program for influencers in the self-hosting / indie hacker space
 **Agency channel:**
 - Create an "Agency Partner" page — explain multi-client dashboard capabilities
 - Reach out directly to 50 small agencies who post about GDPR/analytics on Twitter/LinkedIn
 - Offer bulk pricing and white-labeling for agencies managing 20+ sites
 ---
 ## 8. Content Calendar (First 90 Days)
 | Week | Content | Channel |
 |---|---|---|
 | 1 | Launch post — "I built a GDPR-compliant analytics platform" | HN, Reddit, Dev.to |
 | 1 | Product Hunt submission | Product Hunt |
 | 2 | Demo video (90 seconds, no voiceover) | Twitter, LinkedIn |
 | 3 | Tutorial: "Deploy in 10 minutes on a $5 VPS" | Blog, Dev.to, YouTube |
 | 4 | "How I built the data pipeline" (technical deep-dive) | HN, Dev.to |
 | 5 | Comparison: "vs Plausible" | Blog, SEO |
 | 6 | Integration guide: Next.js | Blog, r/nextjs |
 | 7 | Comparison: "vs Matomo" | Blog, SEO |
 | 8 | "3 months of building in public" update | Twitter, HN |
 | 9 | Integration guide: WordPress | Blog, r/Wordpress |
 | 10 | Webinar: "Self-hosted analytics for GDPR compliance" | LinkedIn Live |
 | 11 | Community showcase — what users are tracking | Blog, Discord |
 | 12 | Roadmap reveal — what's coming in the next quarter | GitHub, Discord |
 ---
 ## 9. Distribution Channels — Priority Order
 | Channel | Effort | Expected Reach | Priority |
 |---|---|---|---|
 | GitHub (quality README + OSS) | Low | Very high (developer discovery) | 🔴 Critical |
 | Hacker News Show HN | Low | High | 🔴 Critical |
 | Product Hunt | Medium | High | 🔴 Critical |
 | Reddit (r/selfhosted, r/webdev) | Low | Medium | 🟡 High |
 | SEO / blog content | High | Very high (long-term) | 🟡 High |
 | Twitter/X #buildinpublic | Low | Medium | 🟡 High |
 | Dev.to / Hashnode | Medium | Medium | 🟡 High |
 | YouTube tutorials | High | High (long-term) | 🟢 Medium |
 | LinkedIn | Medium | Medium (agencies) | 🟢 Medium |
 | Newsletter sponsorships (TLDR, Bytes) | High (cost) | High | 🟢 Medium |
 | Laravel News | Low | High (niche) | 🟢 Medium |
 | Podcast appearances | Medium | Medium | ⚪ Low |
 ---
 ## 10. Key Metrics
 ### Awareness
 - GitHub stars (target: 500 at end of month 2, 2,000 at end of month 6)
 - Website unique visitors/month
 - Organic search impressions
 ### Acquisition
 - GitHub clones/downloads
 - Docker Hub pulls
 - New self-hosted installs (estimated from tracking snippet registrations)
 - Managed hosting signups
 ### Activation
 - % of signups who add a website within 24 hours
 - % who receive their first tracking event within 48 hours
 ### Retention
 - Weekly active installs (websites with at least one event in 7 days)
 - Managed hosting monthly churn rate (target: <3%)
 ### Revenue (Phase 3+)
 - MRR — managed hosting subscriptions
 - ARPU — average revenue per managed hosting customer
 - LTV:CAC ratio (target: >3:1)
 ---
 ## 11. Messaging — Copy Bank
 ### Taglines
 - "Your analytics. Your server. Your data."
 - "The analytics platform Google doesn't want you to build."
 - "Full-featured. Self-hosted. Free forever."
 - "Stop paying per pageview. Own your data."
 - "Privacy-first analytics for people who care about both words."
 ### One-liner for directories and bios
 > A self-hosted, open-source web analytics platform with real-time dashboards, goals, funnels, segments, and a full API — GDPR-compliant by design.
 ### Pain-point headlines (for landing page A/B tests)
 - "GA4 is confusing. Cookie banners are annoying. There's a better way."
 - "Why are you still paying $19/month per website for basic analytics?"
 - "Your visitors' data shouldn't live on Google's servers."
 - "Analytics that respects your users — and your budget."
 ---
 ## 12. Launch Checklist
 - [ ] Write a comprehensive GitHub README with screenshots, quick-start, and feature list
 - [ ] Create a live demo instance at `demo.youranalytics.app` with realistic seed data
 - [ ] Record a 90-second demo video (dashboard walkthrough, no talking needed)
 - [ ] Write `docker-compose.yml` for one-command local setup
 - [ ] Submit a one-click deploy to Railway or Render
 - [ ] Set up a landing page (separate from the app) with pricing and docs
 - [ ] Open GitHub Discussions for community support
 - [ ] Create a Discord server
 - [ ] Write the Product Hunt submission (tagline, description, first comment)
 - [ ] Write the Hacker News Show HN post
 - [ ] Prepare 5 Reddit posts tailored to each subreddit's culture
 - [ ] Write a launch blog post on Dev.to
 - [ ] Build a list of 50 relevant Twitter/LinkedIn accounts to engage with at launch
 - [ ] Set up Google Search Console and submit sitemap
 - [ ] Schedule the Product Hunt launch for a Tuesday at 00:01 PST
 ---
 ## 13. Risk & Mitigation
 | Risk | Likelihood | Impact | Mitigation |
 |---|---|---|---|
 | Crowded market (Umami, Matomo) | High | Medium | Differentiate on full feature set + developer experience |
 | "Just use Plausible" objections | High | Low | Free self-hosting undercuts their price argument entirely |
 | Self-hosting barrier too high | Medium | High | One-click deploy, `docker-compose`, managed hosting option |
 | Feature parity with GA4 expected | Medium | Medium | Clearly scope to product analytics, not advertising attribution |
 | Laravel not seen as "serious" for analytics | Low | Medium | Technical blog content showing architecture depth |
 | Maintenance burden for OSS | Medium | High | Clear contribution guide, automated testing, small focused scope |
 ---
 *This plan is a living document. Revisit and update after each major milestone.*
@@ -0,0 +1,242 @@
 # Analytics Platform — Project Status
 > Last updated: 2026-05-25
 ---
 ## What Is This
 A self-hosted web analytics platform built with Laravel 11 — a privacy-focused alternative to Google Analytics or Plausible. Users add a lightweight JavaScript snippet to their website and get real-time dashboards, AI-ready data pipelines, goal/funnel tracking, and a full REST API.
 ---
 ## Tech Stack
 | Layer | Choice |
 |---|---|
 | Backend | Laravel 11, PHP 8.2+ |
 | Auth | Laravel Fortify (2FA ready) |
 | Frontend | Blade + Alpine.js + Tailwind CSS |
 | Charts | Chart.js |
 | Database | SQLite (dev) / MySQL or PostgreSQL (prod) |
 | Queue | Database driver (dev) / Redis + Horizon (prod) |
 | API | Laravel Sanctum (token auth) |
 | Geolocation | stevebauman/location |
 | Bot detection | jaybizzle/crawler-detect |
 | Build | Vite |
 ---
 ## Feature Status
 ### ✅ Done — Core Platform
 **Authentication & Users**
 - Registration, login, password reset, email verification via Fortify
 - Two-factor authentication support
 - Profile management
 - API token management (Sanctum)
 **Website Management**
 - Full CRUD for tracked websites
 - Embed snippet page with copy-ready `<script>` tag
 - WebsitePolicy — all queries scoped to authenticated owner
 **Data Collection Pipeline**
 - `POST /api/e` and `POST /api/collect` endpoints
 - Async ingestion via `ProcessTrackingPayload` queued job
 - Bot filtering (CrawlerDetect)
 - Domain validation (rejects spoofed tracking IDs)
 - IP geolocation → country, region, city on Visitor
 - CORS middleware for cross-origin beacons
 - Tracking pixel (1×1 GIF) as no-JS fallback
 - Rate limiting (120 req/min per IP)
 - Ad-blocker resistant alternate endpoints (`/cdn/feedback`, `/cdn/resources/`)
 **Dashboard**
 - Date-range picker (today / 7d / 30d / custom)
 - Metric cards: page views, unique visitors, sessions, bounce rate, avg session duration, pages/session
 - Visitors & page views chart (daily/hourly granularity)
 - Real-time active visitors widget (last 5 minutes)
 - Comparison mode vs. previous period with delta %
 - Goal conversion sparklines
 **Reports — Audience**
 - Geographic: visitors by country, region, city (table + world map)
 - Technology: browser, OS, device type, screen resolution
 - Language: browser language breakdown
 - New vs. returning visitors
 **Reports — Acquisition**
 - Traffic sources (direct, organic, referral, social)
 - UTM campaigns (source, medium, campaign)
 - Top referrers
 **Reports — Behavior**
 - Top pages (views, unique views, avg time, bounce rate)
 - Landing pages (entry pages with session count and bounce rate)
 - Exit pages
 **Reports — Events**
 - Events overview (grouped by name/category/action)
 - Event detail drill-down (label/value breakdown)
 - Event trending chart
 **Reports — Conversions**
 - Goal completions, conversion rate, goal value totals
 **Goals & Conversions**
 - 4 goal types: URL destination, event match, duration, pages per session
 - GoalEvaluationService — evaluates goals on every incoming payload
 - Conversion rate reporting
 **Advanced Features**
 - Funnels — multi-step conversion tracking with drop-off visualization
 - Segments — filter all reports by visitor attributes
 - Custom dashboards — pin widgets to a personal overview
 - Alerts — notify on traffic spikes/drops/goal thresholds (email + in-app)
 - Annotations — add notes to specific dates on charts
 - Data export — CSV export for any report
 - UTM builder — in-app campaign URL generator
 **API (v1)**
 - `GET /api/v1/websites` — list websites
 - `GET /api/v1/websites/{id}/stats` — summary metrics with date-range params
 - `GET /api/v1/websites/{id}/pages` — top pages
 - `GET /api/v1/websites/{id}/referrers` — traffic sources
 - `GET /api/v1/websites/{id}/events` — events
 - `GET /api/v1/websites/{id}/visitors` — audience breakdown
 - JSON:API resource classes for consistent formatting
 - Rate limiting per token
 **Data Aggregation**
 - `daily_aggregates` table — pre-computed per-website daily metrics
 - `page_daily_aggregates` table — per-page daily metrics
 - `analytics:aggregate` Artisan command (runs daily at 02:00)
 - Hybrid query strategy: aggregates for past days, raw tables for today
 - `analytics:purge` command — purge raw data older than retention window
 - Configurable `data_retention_days` per website (default: 365)
 **Performance & Indexes**
 - Composite indexes on all date-range + website_id query paths
 - SQLite-compatible index migrations (also works with MySQL/PostgreSQL)
 **Testing**
 - 80 tests, 0 failures
 - Feature tests: `CollectController`, `WebsiteController`, Auth flows
 - Unit tests: `AnalyticsQueryService`, `GoalEvaluationService`
 - Model factories for all analytics models
 - `withoutVite()` in base TestCase — tests run without a built frontend
 ---
 ### 🔲 Not Yet Done
 | Item | Notes |
 |---|---|
 | **User Flow / Sankey diagram** | Intentionally deferred — complex to visualize, low priority for v1 |
 | **Production database** | SQLite is dev-only; set up MySQL or PostgreSQL before launch |
 | **Redis + Horizon** | Replace database queue driver for real traffic; Horizon gives a monitoring UI |
 | **Cron / scheduler** | Configure `schedule:run` on the server — needed for aggregation, purge, and alerts |
 | **HTTPS + CDN for tracker JS** | Tracker script should load from a CDN subdomain to avoid ad-blockers |
 | **Error monitoring** | Wire up Sentry or Flare for production error tracking |
 | **Database backups** | Automate daily dumps with offsite storage |
 | **Dusk browser tests** | UI interaction tests deferred — requires Dusk + ChromeDriver setup |
 ---
 ## Running Locally
 ```bash
 cd ~/Projects/analytics
 composer install
 cp .env.example .env
 php artisan key:generate
 php artisan migrate
 npm install && npm run build
 composer run dev       # starts web server + queue worker + log viewer + Vite
 ```
 App runs at `http://localhost:8000`.
 ### Background processes required
 ```bash
 # Queue worker — processes tracking events (critical)
 php artisan queue:work database --tries=3
 # Scheduler — aggregation, purge, alerts (critical)
 php artisan schedule:work
 # OR add to crontab for production:
 # * * * * * cd /path/to/analytics && php artisan schedule:run >> /dev/null 2>&1
 ```
 ---
 ## Deployment Checklist
 - [ ] Provision server (Ubuntu 22+ recommended)
 - [ ] Install PHP 8.2+, Nginx, MySQL/PostgreSQL, Redis, Node
 - [ ] Clone repo, `composer install --no-dev`, `npm ci && npm run build`
 - [ ] Set `APP_ENV=production`, `APP_DEBUG=false`, configure `.env`
 - [ ] Run `php artisan migrate --force`
 - [ ] Run `php artisan config:cache route:cache view:cache`
 - [ ] Configure Supervisor for queue worker (see `HOWTO.md`)
 - [ ] Add crontab entry for `schedule:run`
 - [ ] Point Nginx document root to `public/`
 - [ ] Set up SSL (Let's Encrypt)
 - [ ] Set up CNAME for tracker script (e.g. `track.yourdomain.com`)
 - [ ] Configure Sentry DSN in `.env`
 - [ ] Set up automated database backups
 ---
 ## Key Artisan Commands
 | Command | Description | Schedule |
 |---|---|---|
 | `analytics:aggregate` | Roll up yesterday's raw data into aggregates | Daily 02:00 |
 | `analytics:purge --force` | Delete raw data older than retention window | Daily 03:00 |
 | `analytics:check-alerts` | Evaluate alert rules and send notifications | Every hour |
 | `queue:work database --tries=3` | Process tracking payloads | Always-on process |
 ---
 ## Architecture Notes
 ### Data Flow
 ```
 Client website (JS snippet)
  → POST /api/e  (CollectController)
  → ProcessTrackingPayload job (queued)
  → Creates/updates: Visitor, AnalyticsSession, PageView or Event
  → GoalEvaluationService checks active goals
  → Daily: analytics:aggregate rolls raw → daily_aggregates
  → Dashboard queries: aggregates for history + raw tables for today
 ```
 ### Collector Extraction (future)
 The `collector_app_plan.md` documents a plan to split the data collection endpoints into a separate Laravel app for independent scaling. This is not needed yet but the code is structured to make it straightforward — `CollectController`, `TrackingScriptController`, `ProcessTrackingPayload`, and `GoalEvaluationService` are all self-contained.
 ---
 ## Database Schema (Core Tables)
 | Table | Purpose |
 |---|---|
 | `websites` | Tracked websites, settings, tracking ID |
 | `visitors` | Unique visitors with device, browser, location |
 | `analytics_sessions` | Sessions with UTM params, entry/exit page, duration |
 | `page_views` | Individual page visits |
 | `events` | Custom events with category, label, value |
 | `goals` | Conversion goal definitions (4 types) |
 | `goal_conversions` | Goal completion records |
 | `funnels` | Multi-step funnel definitions |
 | `segments` | Custom visitor segment definitions |
 | `alerts` | Alert rule definitions |
 | `alert_notifications` | Triggered alert history |
 | `annotations` | Date annotations visible on charts |
 | `dashboard_widgets` | Custom dashboard layout per user |
 | `daily_aggregates` | Pre-computed daily metrics per website |
 | `page_daily_aggregates` | Pre-computed daily metrics per page |