alexei.dolgolyov
8cb836e16c
Replace all if/else chains keyed on provider type strings with a descriptor-driven architecture. Each provider type (immich, gitea, planka, scheduler, nut, google_photos) has a descriptor in frontend/src/lib/providers/ that declares config fields, event tracking fields, collection metadata, validation, and hooks. Components now use getDescriptor(type) and render dynamically. Dashboard provider card shows provider name + type when global filter is active. Grid-items derived from registry.
4.7 KiB
4.7 KiB
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)
- Restart backend after ANY change to
packages/server/orpackages/core/— see dev-servers.md for the one-liner. - Overlays MUST use
position: fixedwith inline styles andz-index: 9999— see frontend-architecture.md. - Template variables must be updated in 6 files simultaneously — see template-system.md.
- Entity cache — shared entities use
$state-based caches infrontend/src/lib/stores/caches.svelte.ts. Always use cache for cross-page data; invalidate after mutations — see frontend-architecture.md. - Selector placeholders — use plain text without decorative dashes.
Select provider...not— Select provider —— see frontend-architecture.md. - Telegram API — ALL Telegram Bot API calls (sendMessage, sendPhoto, sendMediaGroup, etc.) MUST go through
TelegramClientinpackages/core/src/notify_bridge_core/notifications/telegram/client.py. NEVER duplicate sending logic in command handlers, API routes, or services. IfTelegramClientlacks a method you need, add it there. - 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())
- Jinja2 notification templates for each locale in
- No provider-specific hardcoding — ALL provider-specific UI logic lives in provider descriptors (
frontend/src/lib/providers/). NEVER addif (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_slotsorcapabilities.commands, notprovider.type === 'immich' - Template variable helpers: ALL provider types must have entries in
get_template_variables()
- Form fields, validation, config building → defined in the descriptor's
- New provider descriptor checklist — when adding a new service provider, create a descriptor file in
frontend/src/lib/providers/{name}.tsand register it inindex.ts. The descriptor must define:type,defaultName,icon,hasUrl,configFields,buildConfig(),hasConfigChanged(),eventFields,collectionMeta(ornull). Optional:extraTrackingFields,featureSections,webhookUrlPattern,webhookBased,onBeforeSave. Also add i18n keys:providers.type{PascalName}andgridDesc.provider{PascalName}in bothen.jsonandru.json.