TimeTracker/docs/CALENDAR_AGENDA_FEATURE.md

Calendar/Agenda Support Documentation

Overview

The Calendar/Agenda feature in TimeTracker provides a comprehensive view of all your events, tasks, and time entries in one place. This feature helps you plan your work, schedule meetings, and track deadlines more effectively.

Features

Calendar Views

The calendar supports three different view modes:

1. Day View: Shows hourly time slots for a single day with all events and time entries
2. Week View: Displays a weekly grid with events across 7 days
3. Month View: Traditional monthly calendar with events displayed on each day

Event Management

Event Types

• Event: General calendar events
• Meeting: Scheduled meetings with clients or team members
• Appointment: One-on-one appointments
• Reminder: Simple reminders for tasks or deadlines
• Deadline: Important deadlines linked to tasks or projects

Event Properties

Each calendar event can have the following properties:

• Title (required): The name of the event
• Description: Detailed description of the event
• Start Time (required): When the event starts
• End Time (required): When the event ends
• All-Day: Mark event as all-day (no specific time)
• Location: Physical or virtual location
• Color: Custom color for visual organization
• Reminder: Set reminder (5, 15, 30 minutes, 1 hour, or 1 day before)
• Private: Mark event as private (visible only to you)

Associated Items

Events can be linked to:

• Project: Associate event with a specific project
• Task: Link event to a task for better tracking
• Client: Connect event to a client

Recurring Events

Create events that repeat on a schedule:

• Set recurrence pattern using RRULE format
• Example: FREQ=WEEKLY;BYDAY=MO,WE,FR for events every Monday, Wednesday, and Friday
• Set an optional end date for the recurrence

Integration with Tasks and Time Entries

The calendar automatically displays:

• Tasks with due dates: Shown as badges on their due date
• Time entries: Your tracked time appears on the calendar
• Toggle visibility of these items using the filter checkboxes

User Guide

Accessing the Calendar

1. Log in to TimeTracker
2. Click on the Calendar link in the navigation menu
3. The calendar will open with the current month view

Creating a New Event

Method 1: Using the "New Event" Button

1. Click the "New Event" button at the top of the calendar
2. Fill in the event details:
   • Enter a title
   • Set start and end dates/times
   • Add optional description, location, etc.
   • Link to project, task, or client if desired
3. Click "Create Event" to save

Method 2: Quick Creation (Month View)

1. In month view, click on any date cell
2. This opens the new event form with the date pre-filled
3. Complete the event details and save

Viewing Events

In Calendar View

• Events appear as colored badges on their scheduled dates
• In month view, up to 3 events are shown per day
• If more than 3 events exist, a "+X more" indicator appears
• Click any event badge to view its details

Event Detail Page

1. Click on an event to view its full details
2. The detail page shows:
   • Full event information
   • Associated project, task, or client (with links)
   • Duration calculation
   • Created and updated timestamps

Editing Events

1. Click on an event to open its detail page
2. Click the "Edit" button
3. Make your changes
4. Click "Update Event" to save

Deleting Events

1. Open the event detail page
2. Click the "Delete" button
3. Confirm the deletion

Drag and Drop (Coming Soon)

Future versions will support:

• Dragging events to reschedule them
• Resizing events to adjust duration

Filtering the Calendar

Use the checkboxes at the top of the calendar to toggle visibility:

• Events: Show/hide calendar events
• Tasks: Show/hide tasks with due dates
• Time Entries: Show/hide tracked time

Navigation

• Today: Jump to today's date
• Previous/Next: Navigate to previous/next day, week, or month
• Date Selector: Click on the date display to pick a specific date

API Documentation

API Endpoints

Get Events in Date Range

GET /api/calendar/events?start={start_date}&end={end_date}&include_tasks={boolean}&include_time_entries={boolean}

Parameters:

• start: ISO 8601 datetime (required)
• end: ISO 8601 datetime (required)
• include_tasks: Include tasks with due dates (default: true)
• include_time_entries: Include time entries (default: true)

Response:

{
  "events": [...],
  "tasks": [...],
  "time_entries": [...]
}

Create Event

POST /api/calendar/events
Content-Type: application/json

Request Body:

{
  "title": "Team Meeting",
  "description": "Weekly sync",
  "start": "2025-01-15T10:00:00",
  "end": "2025-01-15T11:00:00",
  "allDay": false,
  "location": "Conference Room A",
  "eventType": "meeting",
  "projectId": 1,
  "taskId": null,
  "clientId": null,
  "color": "#3b82f6",
  "reminderMinutes": 30,
  "isPrivate": false,
  "isRecurring": false,
  "recurrenceRule": null,
  "recurrenceEndDate": null
}

Response:

{
  "success": true,
  "event": { /* event object */ },
  "message": "Event created successfully"
}

Update Event

PUT /api/calendar/events/{event_id}
Content-Type: application/json

Request Body: Same as create (partial updates supported)

Delete Event

DELETE /api/calendar/events/{event_id}

Response:

{
  "success": true,
  "message": "Event deleted successfully"
}

Move Event (Drag & Drop)

POST /api/calendar/events/{event_id}/move
Content-Type: application/json

Request Body:

{
  "start": "2025-01-16T10:00:00",
  "end": "2025-01-16T11:00:00"
}

Resize Event

POST /api/calendar/events/{event_id}/resize
Content-Type: application/json

Request Body:

{
  "end": "2025-01-15T12:00:00"
}

Database Schema

CalendarEvent Model

class CalendarEvent(db.Model):
    id = Integer (Primary Key)
    user_id = Integer (Foreign Key to users.id)
    title = String(200) (Required)
    description = Text
    start_time = DateTime (Required, Indexed)
    end_time = DateTime (Required, Indexed)
    all_day = Boolean (Default: False)
    location = String(200)
    event_type = String(50) (Default: 'event', Indexed)
    
    # Associations
    project_id = Integer (Foreign Key to projects.id)
    task_id = Integer (Foreign Key to tasks.id)
    client_id = Integer (Foreign Key to clients.id)
    
    # Recurring events
    is_recurring = Boolean (Default: False)
    recurrence_rule = String(200)  # RRULE format
    recurrence_end_date = DateTime
    parent_event_id = Integer (Foreign Key to calendar_events.id)
    
    # Reminders and customization
    reminder_minutes = Integer
    color = String(7)  # Hex color code
    is_private = Boolean (Default: False)
    
    # Timestamps
    created_at = DateTime
    updated_at = DateTime

Relationships

• user: Many-to-one relationship with User
• project: Many-to-one relationship with Project
• task: Many-to-one relationship with Task
• client: Many-to-one relationship with Client
• parent_event: Self-referential for recurring event instances
• child_events: One-to-many relationship for recurring event series

Migration

The calendar feature is added via Alembic migration:

# Migration file: migrations/versions/034_add_calendar_events_table.py
flask db upgrade

This creates the calendar_events table with all necessary indexes and foreign key constraints.

Permissions

• Users can:

  • Create their own events
  • View their own events
  • Edit their own events
  • Delete their own events
  • View events linked to their assigned tasks

• Admins can:

  • View all events (except private events of other users)
  • Edit any event
  • Delete any event

Best Practices

Event Organization

1. Use Colors Wisely: Assign colors to different event types for quick visual identification

   • Blue (#3b82f6) for regular meetings
   • Red (#ef4444) for deadlines
   • Green (#10b981) for client appointments
   • Purple (#8b5cf6) for personal events

2. Link to Projects: Always link events to projects when relevant for better reporting

3. Set Reminders: Use reminders for important meetings to avoid missing them

4. Use Recurring Events: Set up recurring events for weekly meetings instead of creating them manually

Performance Tips

1. The calendar loads events for the visible date range only
2. Large organizations should consider archiving old events (older than 6 months)
3. Use the filters to focus on what's important

Integration with Workflows

1. Task Planning: Create events for task work sessions
2. Client Meetings: Link meetings to clients for better relationship tracking
3. Project Milestones: Use deadline events for project milestones
4. Time Blocking: Create events to block time for focused work

Troubleshooting

Events Not Showing

1. Check date range - ensure events fall within the visible calendar range
2. Verify filters - ensure event type is not filtered out
3. Check permissions - private events are only visible to their creator

Cannot Edit Event

• Verify you are the event owner or an admin
• Check that the event still exists
• Ensure you're logged in with the correct account

Recurring Events Not Working

• Verify RRULE format is correct
• Check that recurrence end date is after start date
• Ensure parent event exists for child instances

Technical Details

Frontend

• JavaScript: app/static/calendar.js - Calendar rendering and interaction
• CSS: app/static/calendar.css - Calendar styling
• Templates: app/templates/calendar/ - HTML templates

Backend

• Models: app/models/calendar_event.py - Data model
• Routes: app/routes/calendar.py - API and view routes
• Tests: tests/test_calendar_event_model.py, tests/test_calendar_routes.py

Testing

Run calendar tests:

# Model tests
pytest tests/test_calendar_event_model.py -v

# Route tests
pytest tests/test_calendar_routes.py -v

# All calendar tests
pytest tests/test_calendar* -v

# Smoke tests
pytest tests/test_calendar* -m smoke

Future Enhancements

Potential future improvements:

1. iCal/ICS Import/Export: Import events from other calendar applications
2. Sharing: Share events with other users or teams
3. Email Notifications: Send email reminders for events
4. Mobile App: Dedicated mobile calendar view
5. Time Zone Support: Better handling of events across time zones
6. Event Templates: Create reusable event templates
7. Attendees: Add multiple attendees to events
8. Conflict Detection: Warn about overlapping events

Support

For issues or feature requests related to the calendar:

1. Check this documentation first
2. Review the test files for examples
3. Check the GitHub issues for known problems
4. Contact your system administrator

Version History

• Version 1.0 (2025-10-27): Initial calendar/agenda support
  • Day, week, and month views
  • Event CRUD operations
  • Integration with tasks and time entries
  • Recurring event support
  • API endpoints for all operations

Related Documentation

• TimeTracker User Guide
• API Documentation
• Task Management Guide
• Project Management Guide