Usage Tracking

SaaSStinger Lite tracks important workspace activity through a dedicated usage collection.

Rather than calculating counts every time the application loads, usage metrics are updated as changes occur. This keeps dashboard queries fast while providing a foundation for future subscription plans and feature limits.

At launch, Lite tracks usage only. It does not enforce plan limits.

What You'll Learn

In this guide you'll learn:

• Why usage tracking exists
• What metrics are tracked
• How usage documents are created
• When counters are updated
• How usage supports future subscriptions
• Best practices for extending the system

Why Track Usage?

Many SaaS applications need to answer questions such as:

• How many members does this workspace have?
• How many invitations have been sent?
• How many audit log entries exist?
• How many users have been created?

Calculating these values with Firestore queries every time a page loads becomes increasingly expensive as data grows.

Instead, SaaSStinger Lite maintains lightweight counters that are updated whenever relevant actions occur.

Usage Architecture

Each workspace has exactly one usage document.

Workspace
     │
     ▼
Usage Document
     │
     ├── seatsUsed
     ├── usersCreated
     ├── invitesCreated
     └── auditLogsCreated

The usage document is always associated with a single workspace.

Architecture Note

Usage tracking is intentionally separated from business data.

Projects, members, and audit logs remain the source of truth, while the usage document stores summary counters for fast retrieval.

Usage Document

A typical usage document contains:

{
  workspaceId: string

  seatsUsed: number

  usersCreated: number

  invitesCreated: number

  auditLogsCreated: number

  createdAt: Timestamp

  updatedAt: Timestamp
}

Each field tracks a specific aspect of workspace activity.

Current Metrics

seatsUsed

Tracks the number of active workspace members.

This value increases when a new membership is created and decreases when a member is removed.

usersCreated

Tracks the number of users created within the workspace lifecycle.

This metric provides historical insight into workspace growth.

invitesCreated

Tracks the number of invitations created.

Every successful invitation increments this counter.

Revoking an invitation does not reduce the historical count.

auditLogsCreated

Tracks the total number of audit log entries generated for the workspace.

This provides a simple indicator of workspace activity.

Creating the Usage Document

The usage document is created automatically during workspace creation.

The initialization process is:

Create Workspace
       │
       ▼
Create OWNER Membership
       │
       ▼
Create Usage Document
       │
       ▼
Redirect to Dashboard

Developers never need to create usage documents manually.

Updating Usage

Usage counters are updated immediately after successful operations.

Examples include:

Because updates occur as actions happen, dashboard statistics remain current without expensive aggregation queries.

Why Not Calculate Everything Dynamically?

Firestore supports aggregation queries, but calculating usage on every page load introduces additional reads and latency.

By maintaining counters:

• Dashboard widgets load faster.
• Fewer Firestore reads are required.
• The application scales more efficiently as data grows.

This pattern is common in production SaaS applications.

Current Plan Enforcement

At launch, SaaSStinger Lite does not enforce usage limits.

The usage system is responsible only for tracking activity.

Future editions of the starter kit can build on this foundation to support:

• Member limits
• Workspace limits
• Project limits
• Feature entitlements
• Subscription plans

Relationship to limits.ts

Usage data and application limits are intentionally separate concepts.

• Usage answers: "How much is currently being used?"
• Limits answer: "How much is allowed?"

Keeping these responsibilities separate makes the application easier to extend as new plans are introduced.

Best Practice

Treat usage as an operational metric and limits as business rules. This separation keeps the codebase flexible and avoids mixing analytics with authorization.

Extending Usage Tracking

As your application evolves, you may choose to add additional counters such as:

• Projects created
• Tasks created
• Notes created
• Table rows
• File uploads
• API requests

When introducing new counters:

1. Add the field to the usage document.
2. Update it immediately after successful operations.
3. Keep updates inside server-side business logic.
4. Avoid updating counters directly from client components.

Common Mistakes

Recalculating Counts on Every Request

Repeated aggregation queries increase Firestore reads and reduce performance.

Use maintained counters for dashboard statistics.

Updating Counters from the Client

Clients should never modify usage documents directly.

Always perform updates through trusted server-side logic.

Mixing Usage with Authorization

Usage tracking measures activity.

Authorization determines whether an action is permitted.

Keep these concerns separate.

Related Articles

• Workspaces
• Members
• Audit Logs
• RBAC & Permissions
• Dashboard Overview

Next Steps

Now that you understand how SaaSStinger Lite measures workspace activity, continue with Notifications to learn how important events are delivered to users across the application.