Data model – entities

SaaS Tracker’s data model is built around companies, applications, organizations, and events.

Company

• Your account/tenant in the product.
• Multi-tenant isolation is enforced at the company level: data, apps, and credentials are scoped to a single company.
• Has members (users with roles: e.g. Owner, Admin, Member).
• Has a subscription (plan) and optional overrides (negotiated price, limits).
• Contains one or more applications.

Application

• A product or service you track.
• Belongs to one company.
• Has ingest credentials (App UUID + API secret for HMAC signing), ingest URL, and optional environment labels.
• Plan limits may cap the number of applications per company (see Plans & limits).

Organization

• SaaS Tracker is built for B2B SaaS products. Every event must include a customer_org_id, enabling organization-level analytics by default.
• Organizations are derived from event data using customer_org_id. They are materialized dynamically for analytics and health calculations.
• One level today; sub-org hierarchies may be added later.

User (pseudonymized)

• Represented by user_hash (SHA-256 hex string).
• Not stored as a separate identifiable entity.
• Used for distinct user counts, session grouping, and engagement metrics.
• No raw personal identifiers (email, name) are stored in analytics.

Event

• A single event row sent via the Ingest API.
• Stored fields (whitelist only): event, ts_epoch (or server time), path, customer_org_id, session_id, user_hash, environment, plan, plus app/company identifiers. Extra keys in the payload (e.g. properties) are ignored.
• Aggregated for dashboards, event stream, event explorer, and health scores.

Feature definition

• Configurable in the UI (Settings → Feature definitions).
• Defines what “using a feature” means (e.g. which events or conditions).
• Feature definitions operate on organization-level usage patterns.
• Used for Feature adoption and Organization health calculations.

Plan and subscription

• Plan: A tier (Trial, Starter, Growth, Enterprise) with list price, limits (events, apps, retention), and feature flags.
• Subscription: Links a company to a plan; can override price and limits. Tracks overage state and suggested plan when limits are exceeded.
• Plan limits are evaluated separately from ingest, ensuring production traffic is not blocked.

Next: Privacy and retention or Plans & limits.