# Event Schema

This document lists all analytics events tracked by TimeTracker, including their properties and when they are triggered.

## Event Naming Convention

Events follow the pattern `resource.action`:
- `resource`: The entity being acted upon (project, timer, task, etc.)
- `action`: The action being performed (created, started, updated, etc.)

## Authentication Events

### `auth.login`
User successfully logs in

**Properties:**
- `user_id` (string): User ID
- `auth_method` (string): Authentication method used ("local" or "oidc")
- `timestamp` (datetime): When the login occurred

**Triggered:** On successful login via local or OIDC authentication

### `auth.logout`
User logs out

**Properties:**
- `user_id` (string): User ID
- `timestamp` (datetime): When the logout occurred

**Triggered:** When user explicitly logs out

### `auth.login_failed`
Failed login attempt

**Properties:**
- `username` (string): Attempted username
- `auth_method` (string): Authentication method attempted
- `reason` (string): Failure reason
- `timestamp` (datetime): When the attempt occurred

**Triggered:** On failed login attempt

## Project Events

### `project.created`
New project is created

**Properties:**
- `user_id` (string): User who created the project
- `project_id` (string): Created project ID
- `project_name` (string): Project name
- `has_client` (boolean): Whether project is associated with a client
- `timestamp` (datetime): Creation timestamp

**Triggered:** When a new project is created via the projects interface

### `project.updated`
Project is updated

**Properties:**
- `user_id` (string): User who updated the project
- `project_id` (string): Updated project ID
- `fields_changed` (array): List of field names that changed
- `timestamp` (datetime): Update timestamp

**Triggered:** When project details are modified

### `project.deleted`
Project is deleted

**Properties:**
- `user_id` (string): User who deleted the project
- `project_id` (string): Deleted project ID
- `had_time_entries` (boolean): Whether project had time entries
- `timestamp` (datetime): Deletion timestamp

**Triggered:** When a project is deleted

### `project.archived`
Project is archived

**Properties:**
- `user_id` (string): User who archived the project
- `project_id` (string): Archived project ID
- `timestamp` (datetime): Archive timestamp

**Triggered:** When a project is archived

## Timer Events

### `timer.started`
Time tracking timer is started

**Properties:**
- `user_id` (string): User who started the timer
- `project_id` (string): Project being tracked
- `task_id` (string|null): Associated task ID (if any)
- `description` (string): Timer description
- `timestamp` (datetime): Start timestamp

**Triggered:** When user starts a new timer

### `timer.stopped`
Time tracking timer is stopped

**Properties:**
- `user_id` (string): User who stopped the timer
- `time_entry_id` (string): Created time entry ID
- `project_id` (string): Project tracked
- `task_id` (string|null): Associated task ID (if any)
- `duration_seconds` (number): Duration in seconds
- `timestamp` (datetime): Stop timestamp

**Triggered:** When user stops an active timer

### `timer.idle_detected`
Timer is automatically stopped due to idle detection

**Properties:**
- `user_id` (string): User whose timer was stopped
- `time_entry_id` (string): Created time entry ID
- `idle_minutes` (number): Minutes of idle time detected
- `duration_seconds` (number): Total duration
- `timestamp` (datetime): Detection timestamp

**Triggered:** When idle timeout expires and timer is auto-stopped

## Task Events

### `task.created`
New task is created

**Properties:**
- `user_id` (string): User who created the task
- `task_id` (string): Created task ID
- `project_id` (string): Associated project ID
- `priority` (string): Task priority
- `has_due_date` (boolean): Whether task has a due date
- `timestamp` (datetime): Creation timestamp

**Triggered:** When a new task is created

### `task.updated`
Task is updated

**Properties:**
- `user_id` (string): User who updated the task
- `task_id` (string): Updated task ID
- `status_changed` (boolean): Whether status changed
- `assignee_changed` (boolean): Whether assignee changed
- `timestamp` (datetime): Update timestamp

**Triggered:** When task details are modified

### `task.status_changed`
Task status is changed (e.g., todo → in_progress → done)

**Properties:**
- `user_id` (string): User who changed the status
- `task_id` (string): Task ID
- `old_status` (string): Previous status
- `new_status` (string): New status
- `timestamp` (datetime): Change timestamp

**Triggered:** When task is moved between statuses/columns

## Report Events

### `report.generated`
Report is generated

**Properties:**
- `user_id` (string): User who generated the report
- `report_type` (string): Type of report ("summary", "detailed", "project")
- `date_range_days` (number): Number of days in report
- `format` (string): Export format ("html", "pdf", "csv")
- `num_entries` (number): Number of time entries in report
- `timestamp` (datetime): Generation timestamp

**Triggered:** When user generates any report

### `export.csv`
Data is exported to CSV

**Properties:**
- `user_id` (string): User who performed export
- `export_type` (string): Type of export ("time_entries", "projects", "tasks")
- `num_rows` (number): Number of rows exported
- `timestamp` (datetime): Export timestamp

**Triggered:** When user exports data to CSV format

### `export.pdf`
Report is exported to PDF

**Properties:**
- `user_id` (string): User who performed export
- `report_type` (string): Type of report
- `num_pages` (number): Number of pages in PDF
- `timestamp` (datetime): Export timestamp

**Triggered:** When user exports a report to PDF

## Invoice Events

### `invoice.created`
Invoice is created

**Properties:**
- `user_id` (string): User who created the invoice
- `invoice_id` (string): Created invoice ID
- `client_id` (string): Associated client ID
- `total_amount` (number): Invoice total
- `num_line_items` (number): Number of line items
- `timestamp` (datetime): Creation timestamp

**Triggered:** When a new invoice is created

### `invoice.sent`
Invoice is marked as sent

**Properties:**
- `user_id` (string): User who marked invoice as sent
- `invoice_id` (string): Invoice ID
- `timestamp` (datetime): Send timestamp

**Triggered:** When invoice status is changed to "sent"

### `invoice.paid`
Invoice is marked as paid

**Properties:**
- `user_id` (string): User who marked invoice as paid
- `invoice_id` (string): Invoice ID
- `amount` (number): Payment amount
- `timestamp` (datetime): Payment timestamp

**Triggered:** When invoice status is changed to "paid"

## Client Events

### `client.created`
New client is created

**Properties:**
- `user_id` (string): User who created the client
- `client_id` (string): Created client ID
- `has_billing_info` (boolean): Whether billing info was provided
- `timestamp` (datetime): Creation timestamp

**Triggered:** When a new client is created

### `client.updated`
Client information is updated

**Properties:**
- `user_id` (string): User who updated the client
- `client_id` (string): Updated client ID
- `timestamp` (datetime): Update timestamp

**Triggered:** When client details are modified

## Admin Events

### `admin.user_created`
Admin creates a new user

**Properties:**
- `admin_user_id` (string): Admin who created the user
- `new_user_id` (string): Created user ID
- `role` (string): Assigned role
- `timestamp` (datetime): Creation timestamp

**Triggered:** When admin creates a new user

### `admin.user_role_changed`
User role is changed by admin

**Properties:**
- `admin_user_id` (string): Admin who changed the role
- `user_id` (string): Affected user ID
- `old_role` (string): Previous role
- `new_role` (string): New role
- `timestamp` (datetime): Change timestamp

**Triggered:** When admin changes a user's role

### `admin.settings_updated`
Application settings are updated

**Properties:**
- `admin_user_id` (string): Admin who updated settings
- `settings_changed` (array): List of setting keys changed
- `timestamp` (datetime): Update timestamp

**Triggered:** When admin modifies application settings

## System Events

### `system.backup_created`
System backup is created

**Properties:**
- `backup_type` (string): Type of backup ("manual", "scheduled")
- `size_bytes` (number): Backup file size
- `timestamp` (datetime): Backup timestamp

**Triggered:** When automated or manual backup is performed

### `system.error`
System error occurred

**Properties:**
- `error_type` (string): Error type/class
- `endpoint` (string): Endpoint where error occurred
- `user_id` (string|null): User ID if authenticated
- `error_message` (string): Error message
- `timestamp` (datetime): Error timestamp

**Triggered:** When an unhandled error occurs (also sent to Sentry)

## Usage Guidelines

### Adding New Events

When adding new events:

1. Follow the `resource.action` naming convention
2. Document all properties with types
3. Include a clear description of when the event is triggered
4. Update this document before implementing the event
5. Ensure no PII (personally identifiable information) is included unless necessary

### Event Properties

**Required properties (automatically added):**
- `timestamp`: When the event occurred
- `request_id`: Request ID for tracing

**Common optional properties:**
- `user_id`: Acting user (when authenticated)
- `duration_seconds`: For timed operations
- `success`: Boolean for operation outcomes

### Privacy Considerations

**Do NOT include:**
- Passwords or authentication tokens
- Email addresses (unless explicitly required)
- IP addresses
- Personal notes or descriptions (unless aggregated)

**OK to include:**
- User IDs (internal references)
- Counts and aggregates
- Feature usage flags
- Technical metadata

## Event Lifecycle

1. **Definition**: Event is defined in this document
2. **Implementation**: Code is instrumented with `log_event()` or `track_event()`
3. **Testing**: Event is verified in development/staging
4. **Monitoring**: Event appears in PostHog, logs, and dashboards
5. **Review**: Periodic review of event usefulness
6. **Deprecation**: Unused events are removed and documented

## Changelog

Maintain a changelog of event schema changes:

### 2025-10-20
- Initial event schema documentation
- Defined core events for authentication, projects, timers, tasks, reports, invoices, clients, and admin operations

---

**Document Owner**: Product & Engineering Team  
**Last Updated**: 2025-10-20  
**Review Cycle**: Quarterly