Common Change Recipes

These are the safest implementation paths for common Compass changes.

Add A Backend Endpoint

1. Define or extend a shared schema/type in packages/core/src/types if the contract is shared.
2. Add the route to the relevant packages/backend/src/*/*.routes.config.ts.
3. Keep the controller thin in controllers/*.controller.ts.
4. Put business logic in services/*.service.ts.
5. Add controller or service tests.
6. If the endpoint affects realtime UI, decide whether an SSE event is required.

Add A New Event Field

1. Update the event schema/types in packages/core/src/types/event.contracts.ts.
2. Update any mapper or utility code in packages/core/src/mappers or packages/core/src/util/event.
3. Update backend persistence or parser logic if the field is stored or transformed.
4. Update web editors, selectors, and rendering.
5. Add tests in core, web, and backend as needed.

Rule: never treat event shape as web-only unless the field is strictly presentational.

Change Recurring Event Behavior

1. Read packages/core/src/types/event.contracts.ts.
2. Read docs/features/recurring-events-handling.md.
3. Read packages/backend/src/event/classes/compass.event.generator.ts.
4. Read packages/backend/src/event/classes/compass.event.parser.ts.
5. Read packages/backend/src/event/classes/compass.event.executor.ts.
6. Read packages/backend/src/sync/services/event-propagation/compass-to-google/compass-to-google.event-propagation.ts.
7. Update the planner, executor, or scope-expansion path that actually owns the behavior.
8. Add focused tests for the exact recurrence transition you changed.

Do not edit recurring behavior from one layer only.

Common Mistakes

• Changing only the generator/executor without updating the parser's plan — analyzeReplace(...) and analyzeDelete(...) in compass.event.parser.ts are pure functions that turn a target event, its SeriesContext (base + instances), and the mutation input into a ReplacePlan or DeletePlan (replaceThis/replaceSeries/replaceSplit, deleteThis/deleteSeries/deleteSplit). compass.event.generator.ts (generateReplace/generateDelete) expands that plan into concrete records to persist (upsert, deleteIds, primary), and compass.event.executor.ts (executeMutation/executeDelete) is the only layer that touches the DB. If the parser produces the wrong plan kind or wrong instance ids, the generator and executor will faithfully do the wrong thing even though their own logic is correct. Always trace from EventService.replace/EventService.delete in packages/backend/src/event/services/event.service.ts through analyzeReplace/analyzeDelete first.
• Missing a database migration for existing recurring events — existing user data will not be retroactively updated by code changes alone. If you modify how recurring series are stored or processed, add a migration to packages/scripts/src/migrations.
• Testing only the happy-path transition — cancellation transitions follow a different planner path. A test that only covers the primary create/update flow can pass while cancellation transitions break silently.

Triage A Recurrence Sync Regression

1. Reproduce with one event and one expected outcome (which scope: this, thisAndFollowing, or all).
2. Trace the request through EventService.replace/EventService.delete in packages/backend/src/event/services/event.service.ts: confirm seriesContext(...) resolved the right base/instances, then log or debug the ReplacePlan/DeletePlan returned by analyzeReplace/analyzeDelete in packages/backend/src/event/classes/compass.event.parser.ts — check its kind and, for split plans, the deleteInstanceIds and truncatedBase/newBase.
3. Confirm generateReplace/generateDelete in packages/backend/src/event/classes/compass.event.generator.ts expand that plan into the expected upsert/deleteIds/primary (or deleteSeriesId).
4. Confirm executeMutation/executeDelete in packages/backend/src/event/classes/compass.event.executor.ts apply those records via eventRepository.
5. If the DB side is correct but Google is wrong, check CompassToGoogleEventPropagation.propagate(...) in packages/backend/src/sync/services/event-propagation/compass-to-google/compass-to-google.event-propagation.ts — it logs Compass->Google propagation failed on error and Skipping Google effect for user <id> because Google is not connected. when there's no refresh token; check deletedBefore/originalStartByEventId passed in from event.service.ts.
6. Run focused tests:
   • bun run test:backend --runTestsByPath packages/backend/src/event/classes/compass.event.parser.test.ts packages/backend/src/event/classes/compass.event.generator.test.ts packages/backend/src/event/classes/compass.event.executor.test.ts packages/backend/src/sync/services/event-propagation/__tests__/compass-to-google.event-propagation.test.ts --runInBand

Add An SSE Event

1. Add the event name to packages/core/src/constants/sse.constants.ts.
2. Update shared payload types in packages/core/src/types/sse.types.ts if needed.
3. Emit from packages/backend/src/servers/sse/sse.server.ts (or call site that uses publish).
4. Consume it in a web hook under packages/web/src/sse/hooks (listeners on EventSource).
5. Add tests on both emitter and listener sides.

Add Or Change Local Storage Data

1. Update packages/web/src/common/storage/offline-data/offline-data.store.ts if the public store contract changes.
2. Update packages/web/src/common/storage/offline-data/indexeddb-offline-data.store.ts.
3. Add a migration if existing user data could become invalid.
4. Add offline data store and migration tests.

Common Mistakes

• Adding new fields without a migration — existing users already have data in IndexedDB without the new field. If your code expects the field to be present, it will fail silently or throw on their existing records. Always add a migration in packages/web/src/common/storage/migrations/migrations.ts and test the migration path, not just the new code path.
• Testing only the new code path — write a test that starts with pre-migration data (the old shape) and confirms the migration transforms it correctly. A test that only creates fresh data will not catch migration regressions.

Change Repository Selection Or Offline Behavior

1. Start in packages/web/src/events/repositories/event.repository.util.ts.
2. Verify auth-state implications in packages/web/src/auth/session/SessionProvider.tsx and auth-state helpers.
3. Test both never-authenticated and previously-authenticated behavior.

Change A Shared Hotkey Dialog (Day + Week)

Use this for overlays mounted in both WeekView and DayViewContent (for example Dedication).

1. Update the shared dialog component in packages/web/src/views/Week/components/Dedication/Dedication.tsx.
2. Confirm both mount points still render it:
   • packages/web/src/views/Week/WeekView.tsx
   • packages/web/src/views/Day/view/DayViewContent.tsx
3. Keep keyboard behavior aligned:
   • toggle hotkey (ctrl+shift+0)
   • close hotkey (escape when open)
4. Preserve the transition lifecycle:
   • open with showModal() then set visible state
   • close by state first, then dialog.close() in onTransitionEnd
   • keep onCancel(e.preventDefault()) so Escape uses the animated close path

Common pitfall: calling dialog.close() directly in an event handler will skip the CSS exit transition and can produce abrupt UI changes.

Add A Migration

For database migrations:

1. inspect packages/scripts/src/commands/migrate.ts
2. add migration under packages/scripts/src/migrations
3. run the relevant scripts tests

For web local-data migrations:

1. inspect packages/web/src/common/storage/migrations/migrations.ts
2. add the migration to the correct registry
3. add migration tests

Change Environment Handling

1. Update the relevant env schema:
   • backend: packages/backend/src/common/constants/env.constants.ts
   • web: packages/web/src/common/constants/env.constants.ts
2. Confirm startup behavior still works in the intended dev mode.
3. Document any new required variables.

Type A Hook That Accepts A queryOptions-Builder Function

Some web hooks take a TanStack Query queryOptions(...)-returning function as a parameter (for example usePrefetchAdjacentEvents, which takes either weekEventsQueryOptions or dayEventsQueryOptions in packages/web/src/events/queries/usePrefetchAdjacentEvents.ts) so the same hook works for either view. Two approaches that look reasonable both fail to type-check:

1. A named function-type alias with a fixed return shape (e.g. (args) => FetchQueryOptions<never, Error, never>) — never/unknown erase the concrete queryKey tuple type each call site actually returns, producing 'queryKey' requires 3 elements but source may have fewer errors.
2. A union of the concrete function types (typeof weekEventsQueryOptions | typeof dayEventsQueryOptions) — calling a union of functions collapses the return type in a way that fails to unify with the consumer's own generic inference for one of the two shapes.

What works: make the consuming hook itself generic with the same type parameters prefetchQuery/useQuery use (TQueryFnData, TError, TData, TQueryKey extends readonly unknown[]), and type the parameter as (args: EventsQueryArgs) => FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>. Each call site then independently instantiates the generic via inference — no union collapsing, no erased tuple type. TanStack's generic surface is designed for per-call-site inference; piggyback on that instead of fighting it with a shared named type.

Add A New CLI Command

1. Register the command in packages/scripts/src/cli.ts.
2. Implement behavior in packages/scripts/src/commands.
3. Reuse shared CLI utilities from packages/scripts/src/common.
4. Add integration tests in packages/scripts/src/__tests__.