Calendar Feature Guide

Guide to the Calendar module — unified day/week/month view aggregating tasks, habits, and transactions from across all features.

Overview

The Calendar module is a presentation-layer aggregator. It does not own any data — it pulls tasks, habits, and financial transactions from the shared /dashboard endpoint and renders them on a day, week, or month grid. View mode switching is purely client-side state; no server round-trip is needed. Platform-specific feature flags control which data types are visible on Desktop vs Mobile.

Architecture

All data originates from the unified /dashboard endpoint. The Calendar ViewModel filters and groups the response by date for each view mode.

Data Models

Calendar does not define its own models — it reuses models from Tasks, Habits, and Finance.

CalendarState

data class CalendarState(
    val tasks: List<Task> = emptyList(),
    val habits: List<Habit> = emptyList(),
    val transactions: List<Transaction> = emptyList(),
    val isLoading: Boolean = false,
    val isError: Boolean = false,
    val errorMessage: String? = null,
    val viewMode: CalendarViewMode = CalendarViewMode.MONTHLY
)
 
enum class CalendarViewMode { DAILY, WEEKLY, MONTHLY }

API Endpoints

Calendar uses only the dashboard endpoint — it does not have its own routes.

platform header controls which feature data is included in the response (DESKTOP vs MOBILE).

Client Behavior

View mode changes are local — only loading new date ranges triggers a network request.

Key Files

Testing

• Unit: DateUIUtils — weekly range boundaries, month start/end, leap year February.
• Integration: /dashboard with dateTime covering a week; verify tasks, habits, and transactions are all returned.
• Edge cases: view mode switch on the last day of a month; ensure the new date range does not overflow into the next month unexpectedly.

Troubleshooting

Calendar shows no data

• Verify dateTime query param is included — the server returns 400 if it is missing.
• Check platform header matches the client platform (DESKTOP or MOBILE); feature flags gate certain data types.

Transactions missing from calendar

• Finance data is gated by a feature flag on the dashboard endpoint — confirm FINANCE is enabled for the current platform.

Wrong days highlighted

• Timezone mismatch between client and server — dateTime should use the device’s local timezone offset.

Related Docs

• Task logic — how task dates map to calendar days
• Habits — habit recurrence and occurrence dates
• Finance — transaction date fields
• UI & UX — calendar screen layouts and interactions