# Feature Context: Entity Relationship Refactor

## Current State
Starting — no changes made yet. Branch created from master with all telegram-commands work merged.

## Key Design Decisions
- Provider capabilities (notifications, commands) inferred from provider type config, not explicit DB flags
- Tracker renamed to NotificationTracker; TrackerTarget renamed to NotificationTrackerTarget
- New entities: CommandConfig, CommandTracker, CommandTrackerListener
- CommandConfig is provider_type-scoped, shareable across multiple CommandTrackers
- CommandTrackerListener is a junction table (command_tracker_id, listener_type, listener_id) for extensibility
- TelegramBot is dual-purpose: notification target backend + commands listener
- TelegramBot polling/webhook lifecycle tied to CommandTrackerListener ref-counting
- Telegram targets gain chat_action field
- commands_config moves from TelegramBot to CommandConfig entity

## Entity Schema (Target State)
```
ServiceProvider (type: "immich" → infers has_notifications=true, has_commands=true)
  │
  ├─ NotificationTracker (renamed from Tracker)
  │   └─ NotificationTrackerTarget (renamed from TrackerTarget)
  │       ├─ NotificationTarget (+ chat_action for telegram type)
  │       ├─ TrackingConfig (unchanged)
  │       └─ TemplateConfig (unchanged)
  │
  └─ CommandTracker (new)
      ├─ CommandConfig (new, shared, provider_type-scoped)
      └─ CommandTrackerListener (junction → listener_type + listener_id)
          └─ TelegramBot as "telegram_bot" listener type

TelegramBot
  ├─ Used by NotificationTarget (sending messages)
  └─ Used by CommandTrackerListener (receiving commands)
      └─ Smart ref-counting: start polling/webhook when first listener added, stop when last removed
```

## Temporary Workarounds
None yet.

## Cross-Phase Dependencies
- Phase 2 depends on Phase 1 (renamed models)
- Phase 3 depends on Phase 1 (new models for CommandConfig, CommandTracker, CommandTrackerListener)
- Phase 4 depends on Phase 3 (command entities exist in DB/API)
- Phase 5 depends on Phase 2 (renamed API endpoints)
- Phase 6 depends on Phase 3 (command entity APIs)
- Phase 7 depends on all prior phases

## Implementation Notes
- SQLite + async SQLAlchemy via sqlmodel — table renames done via idempotent ALTER TABLE / CREATE TABLE
- No formal test suite — verification via server startup + health check + frontend build
- Migration must handle existing data: rename tables, migrate TelegramBot.commands_config → CommandConfig rows
- Incremental strategy: each phase leaves the codebase fully working