Skip to content

USER_GUIDE.md

Latest commit

 

History

History
538 lines (375 loc) · 13.3 KB

USER_GUIDE.md

File metadata and controls

538 lines (375 loc) · 13.3 KB

TimelyOne User Guide

A comprehensive guide to using TimelyOne, your self-hosted calendar platform.

Table of Contents

  1. Getting Started
  2. First-Time Setup
  3. Connecting Calendars
  4. Using Calendar Views
  5. Managing Events
  6. Booking Links
  7. Settings & Preferences
  8. Dark/Light Theme
  9. Tips & Tricks

Getting Started

What is TimelyOne?

TimelyOne is a self-hosted calendar platform that brings all your calendars (Google, Outlook) into one unified interface. It's designed for personal use, giving you complete control over your calendar data.

Key Features

  • Unified Calendar View: See all your events from multiple calendars in one place
  • Day/Week/Month Views: Switch between different calendar views
  • Event Management: Create, edit, and delete events with Google Meet support
  • Booking Links: Share a link for others to schedule time with you
  • Dark/Light Theme: Choose your preferred theme or use system settings
  • Conflict Detection: Get warnings when events overlap
  • Timezone Support: Automatic timezone detection and conversion

First-Time Setup

When you first access TimelyOne, you'll see a setup wizard:

Step 1: Access the Application

Open your browser and navigate to your TimelyOne installation:

http://localhost:3000

(Or your server's address if deployed)

Step 2: Complete the Setup Form

You'll be prompted to enter:

  1. Name: Your full name
  2. Email: Your email address
  3. Timezone: Auto-detected from your browser (can be changed later)
  4. Password (Optional): Set a password if you want login protection
    • Leave blank if you're using reverse proxy authentication
    • Recommended for internet-facing deployments

Step 3: Submit

Click "Complete Setup" and you'll be taken to the main calendar view.

Note: The setup wizard only appears once. If you need to change these settings later, go to Settings.

Connecting Calendars

Why Connect Calendars?

Connecting your Google Calendar or Outlook Calendar allows TimelyOne to:

  • Fetch and display your existing events
  • Create new events in your calendar
  • Sync changes bidirectionally
  • Check availability for booking links

How to Connect a Calendar

1. Navigate to Connections

Click "Connections" in the top navigation bar.

2. Add a Calendar Account

Click one of the buttons:

  • "Add Google Calendar" - for Gmail/Google Workspace calendars
  • "Add Outlook" - for Microsoft/Office 365 calendars

3. OAuth Authorization

A new window will open asking you to:

  1. Sign in to your Google/Microsoft account
  2. Grant TimelyOne permission to access your calendar
  3. Select which calendars to sync (if prompted)

4. Complete Connection

After authorization:

  • The window will close automatically
  • Click "Refresh Connections" on the Connections page
  • Your account will appear in the "Connected Accounts" list

5. Sync Calendars

Click "Sync All" to fetch your events for the first time.

This may take a moment depending on how many events you have.

Managing Connected Calendars

View Connected Accounts

On the Connections page, you'll see:

  • Connected account email
  • Provider (Google/Microsoft)
  • Status (ACTIVE/SYNCING)
  • Number of calendars
  • Last sync time

Select Calendars to Sync

Click on a connected account to expand it and see all available calendars:

  • Toggle switches: Enable/disable individual calendars
  • Syncing badge: Indicates which calendars are actively syncing
  • Event count: Shows number of events in each calendar

Disconnect an Account

  1. Click on the connected account to expand
  2. Click "Disconnect" button
  3. Confirm the disconnection

Warning: Disconnecting will remove all synced events from TimelyOne. Your events in Google/Microsoft will remain unchanged.

Using Calendar Views

TimelyOne offers three calendar views: Day, Week, and Month.

Switching Views

Use the view toggle in the top-right corner:

  • Day: Single day with hourly timeline
  • Week: 7-day grid view
  • Month: Traditional calendar month

Day View

Best for: Detailed view of a single day's schedule

Features:

  • Hourly time slots (6 AM - 10 PM by default)
  • Current time marker (red line)
  • All-day events at the top
  • Drag and drop to reschedule events

Navigation:

  • Click arrows to go to previous/next day
  • Click "Today" to jump to current day

Week View

Best for: Week-at-a-glance planning

Features:

  • 7 columns (Sunday - Saturday)
  • All-day events row
  • Time slots for each day
  • Color-coded events by calendar
  • Drag and drop within the week

Navigation:

  • Click arrows to move by week
  • Click "Today" to jump to current week

Month View

Best for: Long-term overview

Features:

  • Full calendar month grid
  • Event badges showing time and title
  • "+X more" indicator when day has many events
  • Click any day to see all events

Navigation:

  • Click arrows to move by month
  • Click "Today" to jump to current month
  • Click any day to open day view

Managing Events

Creating a New Event

Method 1: Click Time Slot

  1. Click any time slot in Day or Week view
  2. Event creation dialog opens
  3. Fill in event details (see form fields below)
  4. Click "Create Event"

Method 2: New Meeting Button

  1. Click "New Meeting" button in navigation
  2. Fill in event details
  3. Click "Create Event"

Event Form Fields

Required:

  • Title: Event name (e.g., "Team Standup")

Optional:

  • Description: Additional details
  • Location: Physical or virtual location
  • Start Time: Date and time
  • End Time: Date and time
  • Add Google Meet: Toggle to create video conference link
  • All Day Event: Toggle for all-day events (no specific time)

Editing an Event

  1. Click on any event in the calendar
  2. Event details dialog opens
  3. Click "Edit" button
  4. Modify fields as needed
  5. Click "Save Changes"

Deleting an Event

  1. Click on the event
  2. Click "Delete" button in the dialog
  3. Confirm deletion

Note: Changes are synced to your Google/Microsoft calendar immediately.

Rescheduling Events (Drag and Drop)

In Day/Week View:

  1. Click and hold an event
  2. Drag to new time slot
  3. Release to drop
  4. Event is automatically updated

Tip: You can drag events across days in Week view!

Event Details

Click any event to see full details:

  • Title and description
  • Date and time
  • Duration
  • Location
  • Google Meet link (if available)
  • Attendees
  • Calendar source

Booking Links

Create a personal scheduling page for others to book time with you.

What are Booking Links?

Booking links are your own personal scheduling pages (like Calendly) that you can share with others. People can:

  • See your availability
  • Choose a time slot
  • Book a meeting with you
  • Get automatic calendar invites

Creating a Booking Link

1. Navigate to Booking Link

Click "Booking Link" in the navigation bar.

2. Configure Your Booking Page

Fill in the form:

Basic Information:

  • Title: Page heading (e.g., "Book a Meeting with John")
  • Description: Instructions for visitors
  • URL Slug: Your custom URL (e.g., "john-doe")
    • Your booking page will be at: your-domain.com/book/john-doe

Meeting Settings:

  • Duration Options: Select available meeting lengths
    • 15 minutes
    • 30 minutes
    • 60 minutes
  • Default Duration: Pre-selected option
  • Buffer Time: Minutes before/after meetings (prevents back-to-back)

Calendar Selection:

  • Choose which calendar to check for conflicts
  • Choose which calendar to create new bookings in

Availability:

  • Timezone: Your timezone (for availability calculations)
  • Working Hours: Days and times you're available
    • Monday - Friday: 9:00 AM - 5:00 PM (default)
    • Customize for each day
    • Disable days you're unavailable

3. Save Booking Link

Click "Save Booking Link" or "Update Booking Link".

Sharing Your Booking Link

Copy your booking URL and share it:

  • Via email
  • In your email signature
  • On your website
  • In social media bios
  • In Zoom/Teams profile

Example URL: https://calendar.yourdomain.com/book/john-doe

How Bookings Work

For Visitors:

  1. Open your booking link
  2. See available time slots
  3. Choose a duration (15/30/60 min)
  4. Select a date and time
  5. Enter their details (name, email, notes)
  6. Confirm booking

For You:

  1. Booking appears in your calendar automatically
  2. Both you and the visitor receive calendar invites
  3. Google Meet link is created automatically
  4. Email notifications sent (if configured)

Managing Bookings

View Bookings:

  • Bookings appear as regular events in your calendar
  • Tagged with visitor's email in description

Cancel a Booking:

  • Delete the event from your calendar
  • (Future: Automatic cancellation emails)

Disable Booking Link:

  1. Go to Booking Link page
  2. Toggle "Active" switch to OFF
  3. Save changes
  • Visitors will see "Booking link is currently unavailable"

Settings & Preferences

Access settings by clicking the Settings icon (gear) in the navigation bar.

Profile Settings

Name:

  • Update your display name
  • Shown in booking confirmations

Email:

  • Your primary email address
  • Cannot be changed after setup (contact admin)

Timezone Settings

Auto-Detect:

  • Click "Detect Timezone" to use browser's timezone

Manual Selection:

  • Choose from dropdown list
  • All events will display in this timezone
  • Booking times adjust automatically

Password Settings

Set Password:

  • If you didn't set one during setup
  • Enables login protection

Change Password:

  • Enter current password
  • Enter new password
  • Confirm new password

Security Tips:

  • Use a strong, unique password
  • Consider using a password manager
  • Enable 2FA on your reverse proxy (if applicable)

Account Management

Delete Account:

  • Permanently deletes all your data
  • Removes all calendar connections
  • Cannot be undone
  • Requires confirmation

Dark/Light Theme

TimelyOne includes a comprehensive theme system.

Switching Themes

Click the theme toggle button in the navigation bar (sun/moon icon).

Available Options:

  • Light Mode: Bright, high-contrast interface
  • Dark Mode: Easy on the eyes, great for nighttime
  • System: Automatically follows your OS theme preference

Theme Features

Automatic Adaptation:

  • Event colors adjust for readability
  • All components styled for both themes
  • Smooth transitions when switching

Persistence:

  • Your choice is saved locally
  • Remembered across sessions

Tips for Theme Usage

  • Use System mode to match your OS
  • Use Dark mode for reduced eye strain
  • Use Light mode for printing/screenshots

Tips & Tricks

Keyboard Shortcuts

(Coming soon in future updates)

Best Practices

Calendar Syncing:

  • Run "Sync All" after making changes in Google/Microsoft
  • Sync happens incrementally (only fetches changes)
  • Check "Last Sync" time on Connections page

Event Management:

  • Use descriptive titles for better visibility
  • Add locations to help with planning
  • Enable Google Meet for remote meetings
  • Set all-day events for holidays/travel

Booking Links:

  • Set realistic buffer times (5-15 minutes)
  • Update working hours when schedule changes
  • Disable on vacation days
  • Add clear description of what the meeting is for

Performance:

  • Deselect calendars you don't need to see
  • Disconnect accounts you're not using
  • Keep event titles concise for month view

Troubleshooting Common Issues

Events not showing:

  1. Check that calendar is selected in Connections
  2. Click "Sync All" to refresh
  3. Verify date range (check view filters)

Booking times incorrect:

  1. Check timezone in Settings
  2. Verify working hours in Booking Link config
  3. Ensure calendar is synced

Can't create events:

  1. Verify calendar is connected
  2. Check OAuth permissions
  3. Try disconnecting and reconnecting

For more issues, see TROUBLESHOOTING.md.

Getting Help

Documentation

Support

  • Issues: Report bugs on GitHub
  • Questions: Check documentation first
  • Feature Requests: Open an issue with details

Privacy & Security

Your Data

  • All data stays on your server
  • No third-party analytics
  • No data sent to external services (except Google/Microsoft for calendar sync)
  • Full control over backups and retention

Security Best Practices

  1. Use HTTPS in production (via reverse proxy)
  2. Set strong password if exposed to internet
  3. Keep software updated (npm update regularly)
  4. Backup database regularly
  5. Use firewall to restrict access if self-hosting

OAuth Tokens

  • Stored securely in database
  • Never sent to browser/client
  • Managed by Composio platform
  • Automatically refreshed

Built with privacy in mind. Your calendar, your data, your control.