DefCalendar

Desktop calendar app for Microsoft 365 Exchange Online built with Electron.

• Microsoft sign-in via @azure/msal-node with encrypted token cache
• Multi-account support with calendar selection and custom colors
• Full event CRUD with drag-and-drop move/resize
• Optional physical-location autocomplete and map previews powered by Photon / OpenStreetMap, without an API key
• Meeting responses (accept/tentative/decline)
• Participant free/busy indicators when creating meetings, refreshed as attendees or times change
• Local SQLite cache with configurable periodic sync
• Desktop reminder popup with snooze/dismiss and meeting join
• System tray integration
• React 19 renderer with month/week/day views and mini calendar
• Internationalization (English/Italian)
• Auto-updates via GitHub Releases (stable/prerelease channels)

Stack

• Electron + electron-vite + TypeScript
• React 19 + FullCalendar + Zustand + TanStack Query
• better-sqlite3 (local cache), MSAL Node (auth), Microsoft Graph API
• Zod (validation), i18next (i18n), electron-updater (auto-updates)
• oxlint + oxfmt for linting/formatting, Vitest for testing, Husky for hooks

Local Setup

1. Register a Microsoft Entra application for DefCalendar.
2. Point src/main/auth/app-registration.ts at your public-client app registration, or use MSAL_CLIENT_ID only as a development override.
3. Configure the app for accounts in any organizational directory.
4. Enable the public client desktop/mobile flow.
5. Under Authentication > Add a platform, add Mobile and desktop applications with the redirect URI http://localhost.
6. Grant delegated Microsoft Graph permissions:
   • openid, profile, offline_access
   • User.Read, User.ReadBasic.All, Calendars.ReadWrite, MailboxSettings.Read, Contacts.Read, People.Read
7. Use .env.example for optional development overrides; packaged end users should use the bundled app registration.
8. For tenant-specific development, override MSAL_AUTHORITY.

Scripts

• npm run dev — Start development server
• npm run build — Compile main, preload, and renderer into out/
• npm run lint — Run oxlint
• npm run lint:fix — Apply oxlint autofixes
• npm run format — Format code with oxfmt
• npm run format:check — Check formatting without changes
• npm run test — Run Vitest suite
• npm run test:watch — Run tests in watch mode
• npm run package — Create unpacked distributable
• npm run dist — Create installer artifacts with electron-builder
• npm run dist:publish — Create installer artifacts and publish a GitHub Release

Notes

• Targets Microsoft 365 work/school accounts only.
• Locations are plain text by default, including online meeting names. Use the icon selector to the left of the location field to switch from Location to Map for address suggestions and a small OpenStreetMap area preview. Hovering or focusing the preview reveals the link icon; clicking opens Google Maps. The physical-location choice and selected coordinates are saved locally for each event and retained through synchronization while the address remains unchanged. Map previews load only the visible tiles through Electron's HTTP cache, with an identifying DefCalendar User-Agent; no API key is required.
• Location suggestions use the public Photon API. Searches send only the typed location to Photon after at least three characters and a 500 ms pause. Requests run in the main process, are limited to one per second, and results are cached in memory for five minutes. Returning to a cached query displays results immediately; switching away from the app preserves the open popup and pending search. Previous suggestions remain visible but cannot be selected while a new search is pending. Italian uses local place names; English requests translated names. Street addresses with house numbers use structured searches and exclude conflicting streets or house numbers. When Photon only knows the street, suggestions retain the entered number and explicitly mark it as unverified. The public service permits moderate usage, may throttle requests, and has no availability guarantee. Manual locations remain available when offline or when no result matches. Map data is attributed to OpenStreetMap contributors.
• Participant profile photos use delegated User.ReadBasic.All to read other organizational users' basic profiles, including photos, and Contacts.Read for personal contact photos. See the Microsoft Graph photo permissions. When upgrading an existing Entra app registration, add User.ReadBasic.All to its delegated permissions and sign in again to grant the additional consent. Tenant consent policies may require administrator approval. If GRAPH_SCOPES is overridden, include User.ReadBasic.All there as well; photos without sufficient permission retain initials.
• Participant availability uses Microsoft Graph getSchedule with the existing delegated Calendars.ReadWrite permission; no additional Microsoft 365 consent is required. Exchange calendar sharing and free/busy policies determine which schedules the signed-in account can see. Inaccessible or external mailboxes may show availability as unknown, never as free. Only availability is sent to the UI, without event titles or details. Recurring meetings check the selected time range only.
• AADSTS500113 means the Entra app registration is missing the localhost redirect or public client flows are disabled.
• Shared/delegate calendars are not implemented.
• Recurring events and attendee-managed meetings are shown but edited as read-only, with an Outlook handoff.
• Build Windows installers on native Windows or CI (WSL2 is not suitable).
• Auto-updates use GitHub Releases and are user-initiated from Settings > Sync.
• Publishing updates requires a GH_TOKEN with repository release permissions.