notify-bridge/CLAUDE.md

Project Guidelines

Detailed context is split into focused documents under .claude/docs/. Read the relevant file when working in that area.

Area	File	Key rules
Dev servers & credentials	dev-servers.md	MUST restart backend after code changes; frontend restart on request
Frontend architecture	frontend-architecture.md	Svelte 5 runes, overlays, entity cache system, i18n, auth flow
Backend architecture	backend-architecture.md	SQLAlchemy async constraints, Jinja2 sandbox, route ordering
Entity relationships	entity-relationships.md	Full entity graph and DB conventions
Template system	template-system.md	6-file sync rule for template variables

Critical Rules (always apply)

1. Restart backend after ANY change to packages/server/ or packages/core/ — see dev-servers.md for the one-liner.
2. Overlays MUST use position: fixed with inline styles and z-index: 9999 — see frontend-architecture.md.
3. Template variables must be updated in 6 files simultaneously — see template-system.md.
4. Entity cache — shared entities use $state-based caches in frontend/src/lib/stores/caches.svelte.ts. Always use cache for cross-page data; invalidate after mutations — see frontend-architecture.md.
5. Selector placeholders — use plain text without decorative dashes. Select provider... not — Select provider — — see frontend-architecture.md.
6. Telegram API — ALL Telegram Bot API calls (sendMessage, sendPhoto, sendMediaGroup, etc.) MUST go through TelegramClient in packages/core/src/notify_bridge_core/notifications/telegram/client.py. NEVER duplicate sending logic in command handlers, API routes, or services. If TelegramClient lacks a method you need, add it there.
7. Service provider defaults — when implementing a new service provider, ALWAYS create default notification and command templates and configs. This requires changes across all of these locations:
   • Jinja2 notification templates for each locale in packages/core/src/notify_bridge_core/templates/defaults/{en,ru}/
   • Jinja2 command templates for each locale in packages/core/src/notify_bridge_core/templates/command_defaults/{en,ru}/{provider}/
   • Notification slot mapping in packages/core/src/notify_bridge_core/templates/defaults/loader.py (PROVIDER_SLOT_FILE_MAP)
   • Command slot mapping in packages/core/src/notify_bridge_core/templates/command_defaults/loader.py (PROVIDER_COMMAND_SLOTS)
   • Provider capabilities in packages/core/src/notify_bridge_core/providers/capabilities.py
   • Seed functions in packages/server/src/notify_bridge_server/database/seeds.py (notification templates, command templates, tracking configs, command configs)
   • Template variable definitions in packages/server/src/notify_bridge_server/api/template_configs.py (get_template_variables())
8. No provider-specific hardcoding — ALL provider-specific UI logic lives in provider descriptors (frontend/src/lib/providers/). NEVER add if (type === 'xyz') in components.
   • Form fields, validation, config building → defined in the descriptor's configFields / buildConfig / hasConfigChanged
   • Event tracking checkboxes → eventFields; extra controls → extraTrackingFields; feature sections (periodic/scheduled/memory) → featureSections
   • Collection labels/icons → collectionMeta; webhook URL display → webhookUrlPattern
   • Pre-save hooks (e.g. shared-link validation) → onBeforeSave
   • Components use getDescriptor(type) and render dynamically from the descriptor
   • Feature gating: check capabilities.notification_slots or capabilities.commands, not provider.type === 'immich'
   • Template variable helpers: ALL provider types must have entries in get_template_variables()
9. Nav tree & entity types — when adding a new entity type (target type, bot type, etc.), update the sidebar nav in frontend/src/routes/+layout.svelte. Target types need: { href: '/targets?type={type}', key: 'nav.target{PascalName}', icon: '...', countKey: 'targets_{type}' } in the children array under nav.targets, plus i18n keys nav.target{PascalName} in both locale files. Also add the counter entry targets_{type}: targets.filter(t => t.type === '{type}').length to the counts derived block in +layout.svelte.
10. Template consistency (IMPORTANT) — notification templates and command templates for the same provider MUST use the same formatting patterns. If notification templates wrap URLs in <a href>, show type icons, location, and favorite status for assets, command templates must do the same. The reference pattern is the assets_added notification template. Command handlers must pass rich asset dicts (public_url, city, country, is_favorite, type) to templates — not just id and originalFileName.
11. New provider descriptor checklist — when adding a new service provider, create a descriptor file in frontend/src/lib/providers/{name}.ts and register it in index.ts. The descriptor must define: type, defaultName, icon, hasUrl, configFields, buildConfig(), hasConfigChanged(), eventFields, collectionMeta (or null). Optional: extraTrackingFields, featureSections, webhookUrlPattern, webhookBased, onBeforeSave. Also add i18n keys: providers.type{PascalName} and gridDesc.provider{PascalName} in both en.json and ru.json.
12. Template context variables (IMPORTANT) — when adding new variables to templates, update ALL of these in sync:
    • Runtime context builder: packages/core/src/notify_bridge_core/templates/context.py
    • Variable docs: packages/server/src/notify_bridge_server/api/template_configs.py (get_template_variables())
    • Notification preview sample: packages/server/src/notify_bridge_server/services/sample_context.py (_SAMPLE_CONTEXT)
    • Command preview sample: packages/server/src/notify_bridge_server/api/command_template_configs.py (sample_ctx in preview_raw)
    • Runtime validator whitelist: packages/core/src/notify_bridge_core/templates/validator.py