Add PostHog Event Plan for OpenChat instrumentation

[leoisadev8]

Summary

• Introduces a comprehensive PostHog instrumentation blueprint for the OpenChat monorepo (web, server, extension).
• Documents baseline setup, core event taxonomy, common properties, dashboards, and per-file implementation notes.
• Provides a clear naming convention and rollout plan to guide analytics instrumentation.

Changes

Documentation

• Added new file: posthog.md containing the PostHog Event Plan with detailed guidance across sections 1–6 and next steps.

Details

1. Baseline Setup & Guardrails

• Guidelines for client bootstrap, server capture, identity handling, and super-properties.
• Emphasizes lazy initialization, guarded captures, and consistent user/workspace attribution.

2. Core Event Taxonomy

• Defines a comprehensive set of events (naming convention: scope.action, snake_case).
• Includes events across marketing, authentication, chat, settings, OpenRouter, extension, etc., with trigger points and key properties.
• Encourages alignment with existing events (e.g., auth.sign_in, chat_message_submitted) while standardizing new additions.

3. Common Properties

• Lists super-properties to register globally on the client and server: auth_state, workspace_id, model_id, ui_theme, brand_theme, app_version, deployment, etc.
• Defines server-side properties like origin, ip_hash, latency/status metrics.

4. Dashboards & Insights

• Proposes dashboards to monitor activation, chat health, sync reliability, personalization adoption, attachments, model performance, and guest vs. authenticated retention.
• Suggests slicing data by relevant dimensions (referrers, deployments, models, themes, etc.).

5. Implementation Notes by File

• Outlines where instrumentation should be added or extended across key files (web components, chat flow, settings, sync, server routers, and extension entry points).
• Emphasizes incremental rollout and alignment with existing code paths.

6. Next Steps

• Align engineering on naming conventions and property casing.
• Implement super-property registration and session provenance first.
• Iterate with feature flags, validate in PostHog, and build dashboards iteratively.

Rationale

• This plan provides a single source of truth for instrumenting OpenChat with PostHog.
• Enables cross-team alignment on event coverage, properties, and dashboards.
• Facilitates early signal detection for acquisition, onboarding friction, usage patterns, and extension adoption.

Implementation Notes

• The plan is intended as guidance and should be implemented progressively, with a focus on core flows first (landing, sign-in/up, chat, and settings).
• Names, properties, and event surface should be refined during implementation to ensure consistency with existing events.

Next Steps

• Review for naming consistency and property coverage.
• Start with baseline client/server setup and onboarding events.
• Roll out dashboards in the order outlined, collecting stakeholder feedback.

Test plan

• Review the document for completeness and alignment with codebase.
• Validate naming conventions (scope.action) and property casing (snake_case).
• Plan incremental rollout behind a feature flag and verify events in Live feed.
• Create initial dashboards and verify data correctness with stakeholders.

🌿 Generated by Terry

---

ℹ️ Tag @terragon-labs to ask questions and address PR feedback

📎 Task: https://www.terragonlabs.com/task/1eaeaaf1-cdf8-4da7-af98-d13372cfa049