TimeTracker/docs/features/activity_feed.md

Activity Feed Widget

The Activity Feed Widget provides real-time visibility into team activities and creates a comprehensive audit trail for your TimeTracker instance.

Overview

The Activity Feed automatically tracks and displays all major actions performed in the system, including:

• Project management (create, update, delete, archive)
• Task operations (create, update, delete, status changes, assignments)
• Time tracking (start/stop timer, manual entries, edits)
• Invoice activities (create, send, mark paid)
• Client management
• And more...

Features

Dashboard Widget

The Activity Feed Widget appears on the main dashboard in the right sidebar, displaying:

• Recent Activities: Last 10 activities by default
• User Attribution: Shows who performed each action
• Timestamps: Displays how long ago each action occurred
• Action Icons: Visual indicators for different types of actions
• Entity Details: Clear description of what was done

Filtering

Click the filter icon (🔽) to filter activities by type:

• All Activities
• Projects only
• Tasks only
• Time Entries only
• Invoices only
• Clients only

Real-time Updates

The activity feed automatically refreshes every 30 seconds to show the latest team activities.

User Permissions

Regular Users

• See their own activities
• View activities related to projects they have access to

Administrators

• See all activities across the entire organization
• Access to advanced filtering and export options
• View activity statistics

API Endpoints

Get Activities

GET /api/activities

Query Parameters:

• limit (int): Number of activities to return (default: 50)
• page (int): Page number for pagination (default: 1)
• user_id (int): Filter by specific user (admin only)
• entity_type (string): Filter by entity type (project, task, time_entry, invoice, client)
• action (string): Filter by action type (created, updated, deleted, started, stopped, etc.)
• start_date (ISO string): Filter activities after this date
• end_date (ISO string): Filter activities before this date

Response:

{
  "activities": [
    {
      "id": 123,
      "user_id": 5,
      "username": "john.doe",
      "display_name": "John Doe",
      "action": "created",
      "entity_type": "project",
      "entity_id": 42,
      "entity_name": "New Website",
      "description": "Created project \"New Website\"",
      "extra_data": {},
      "created_at": "2025-10-30T14:30:00Z"
    }
  ],
  "total": 150,
  "pages": 3,
  "current_page": 1,
  "has_next": true,
  "has_prev": false
}

Get Activity Statistics

GET /api/activities/stats?days=7

Query Parameters:

• days (int): Number of days to analyze (default: 7)

Response:

{
  "total_activities": 342,
  "entity_counts": {
    "project": 45,
    "task": 128,
    "time_entry": 156,
    "invoice": 13
  },
  "action_counts": {
    "created": 89,
    "updated": 167,
    "deleted": 12,
    "started": 42,
    "stopped": 32
  },
  "user_activity": [
    {
      "username": "john.doe",
      "display_name": "John Doe",
      "count": 156
    }
  ],
  "period_days": 7
}

Action Types

The system tracks the following action types:

Action	Description	Used For
created	Entity was created	Projects, Tasks, Clients, Invoices
updated	Entity was modified	Projects, Tasks, Time Entries
deleted	Entity was removed	Projects, Tasks, Time Entries
started	Timer started	Time Entries
stopped	Timer stopped	Time Entries
completed	Task marked as done	Tasks
assigned	Task assigned to user	Tasks
commented	Comment added	Tasks
status_changed	Status modified	Tasks, Invoices
sent	Invoice sent to client	Invoices
paid	Payment recorded	Invoices
archived	Entity archived	Projects
unarchived	Entity unarchived	Projects

Entity Types

Activities can be tracked for the following entity types:

• project - Project management
• task - Task operations
• time_entry - Time tracking
• invoice - Invoicing
• client - Client management
• user - User administration (admin only)
• comment - Comments and discussions

Integration Guide

For Developers

To add activity logging to new features, use the Activity.log() method:

from app.models import Activity

Activity.log(
    user_id=current_user.id,
    action='created',  # Action type
    entity_type='project',  # Entity type
    entity_id=project.id,
    entity_name=project.name,
    description=f'Created project "{project.name}"',
    extra_data={'client_id': client.id},  # Optional metadata
    ip_address=request.remote_addr,  # Optional
    user_agent=request.headers.get('User-Agent')  # Optional
)

Best Practices:

1. Always log after successful operations - Log after the database commit succeeds
2. Provide clear descriptions - Make descriptions human-readable
3. Include relevant metadata - Use extra_data for additional context
4. Store entity names - Cache the entity name in case it's deleted later
5. Handle failures gracefully - Activity logging includes built-in error handling

Already Integrated

Activity logging is already integrated for:

• ✅ Projects (create, update, delete, archive, unarchive)
• ✅ Tasks (create, update, delete, status changes, assignments)
• ✅ Time Entries (start timer, stop timer, manual create, edit, delete)
• ⏳ Invoices (create, update, status change, payment, send) - coming soon
• ⏳ Clients (create, update, delete) - coming soon
• ⏳ Comments (create) - coming soon

Use Cases

Team Visibility

• See what your team members are working on
• Track project progress in real-time
• Understand team activity patterns

Audit Trail

• Compliance and record-keeping
• Track who made what changes and when
• Identify suspicious or unusual activity

Project Management

• Monitor task completion rates
• Track project milestones
• Review team productivity

Troubleshooting

• Investigate issues by reviewing recent changes
• Identify when problems were introduced
• Track down missing or deleted items

Configuration

No special configuration is required. The Activity Feed is enabled by default for all users.

Database Indexes

The Activity model includes optimized indexes for:

• User-based queries (user_id, created_at)
• Entity lookups (entity_type, entity_id)
• Date range queries (created_at)

Performance

• Activities are paginated to prevent slow page loads
• Old activities are automatically retained (no automatic cleanup)
• Database queries are optimized with proper indexes
• Widget auto-refreshes are throttled to every 30 seconds

Privacy & Security

Data Retention

• Activities are stored indefinitely by default
• Administrators can manually delete old activities if needed
• Consider implementing a retention policy for compliance

Access Control

• Users can only see their own activities (unless admin)
• Administrators see all activities system-wide
• Activity logs cannot be edited or tampered with
• IP addresses and user agents are stored for security auditing

GDPR Compliance

When a user requests data deletion:

1. Their activities are preserved for audit purposes
2. User information can be anonymized
3. Activities show "Deleted User" for anonymized accounts

Troubleshooting

Activities not appearing?

1. Check permissions - Regular users only see their own activities
2. Verify integration - Ensure the route has Activity.log() calls
3. Database issues - Check logs for database errors
4. Browser cache - Clear cache or hard refresh the dashboard

Widget not loading?

1. Check API endpoint - Visit /api/activities directly
2. JavaScript errors - Check browser console for errors
3. Authentication - Ensure user is logged in
4. Network issues - Check network tab in dev tools

Missing activities for certain actions?

Some features may not have activity logging integrated yet. Check the "Already Integrated" section above.

Future Enhancements

Planned improvements for the Activity Feed:

• Export activities to CSV/JSON
• Email notifications for specific activities
• Advanced search and filtering
• Activity feed for specific projects/tasks
• Webhook integration for external systems
• Custom activity types and actions
• Activity trends and analytics dashboard

Support

For issues or questions about the Activity Feed:

• Check the FAQ
• Review the API Documentation
• Open an issue on GitHub
• Contact support