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 |