docs(backend): align auth and sync behavior documentation

[cursor]

Summary

• Expanded docs/backend/README.md from a status note into a backend orientation page with intent, source anchors, workflow summaries, and operational constraints.
• Updated docs/backend/api-documentation.md to document:
  • POST /api/signout logout cleanup semantics (handleLogoutCleanup, metadata restart behavior, last-session watch teardown, non-blocking cleanup failures)
  • POST /api/sync/import-gcal request body contract ({ force?: boolean }) and force/no-force guardrail behavior.
• Updated docs/features/google-sync-and-websocket-flow.md with:
  • logout cleanup and watch teardown lifecycle during sign-out
  • manual import trigger contract and asynchronous import behavior.

Codepaths covered

• packages/backend/src/common/middleware/supertokens.middleware.handlers.ts
• packages/backend/src/user/services/user.service.ts
• packages/backend/src/sync/controllers/sync.controller.ts
• packages/backend/src/sync/sync.types.ts
• packages/backend/src/sync/services/sync.service.ts
• packages/backend/src/sync/sync.routes.config.ts

Knowledge gaps addressed

• Clarifies how sign-out cleanup interacts with sync metadata and watch lifecycle.
• Documents exact public request contract for /api/sync/import-gcal and what force changes.
• Makes backend docs easier to scan for architecture intent, operational outcomes, and troubleshooting entry points.

  

---

Note

Low Risk
Documentation-only updates; low risk aside from potential confusion if the described auth/sync semantics diverge from runtime behavior.

Overview
Expands docs/backend/README.md into an orientation page with intent, key source anchors, and concise descriptions of core workflows (auth/session, event writes, Google notification ingress) plus operational notes.

Updates backend docs to explicitly document POST /api/signout cleanup semantics (non-blocking handleLogoutCleanup, metadata RESTART, and last-session watch teardown) and the POST /api/sync/import-gcal request-body contract ({ force?: boolean }) and guardrails.

Adds corresponding sections to docs/features/google-sync-and-websocket-flow.md describing logout watch teardown and the manual import trigger contract + asynchronous websocket progress events.

^{Written by Cursor Bugbot for commit da3f57d. This will update automatically on new commits. Configure here.}