Core Entities¶

class CameraStatus(str, Enum):
    ONLINE = "online"
    OFFLINE = "offline"
    ERROR = "error"
    UNKNOWN = "unknown"

-- Check constraint for status values (backend/models/camera.py:93-96)
CHECK (status IN ('online', 'offline', 'error', 'unknown'))

# backend/models/camera.py:114-163
detections: Mapped[list[Detection]]     # One-to-many, cascade delete
events: Mapped[list[Event]]              # One-to-many, cascade delete
camera_zones: Mapped[list[CameraZone]]   # One-to-many, cascade delete
activity_baselines: Mapped[list[ActivityBaseline]]  # One-to-many
class_baselines: Mapped[list[ClassBaseline]]        # One-to-many
scene_changes: Mapped[list[SceneChange]]            # One-to-many

def normalize_camera_id(folder_name: str) -> str:
    """
    "Front Door" -> "front_door"
    "back-yard"  -> "back_yard"
    "Garage"     -> "garage"
    """

# backend/models/camera.py:165-184
@property
def is_deleted(self) -> bool:
    return self.deleted_at is not None

def soft_delete(self) -> None:
    self.deleted_at = datetime.now(UTC)

def restore(self) -> None:
    self.deleted_at = None

-- backend/models/detection.py:141-152
CHECK (media_type IS NULL OR media_type IN ('image', 'video'))
CHECK (confidence IS NULL OR (confidence >= 0.0 AND confidence <= 1.0))
CHECK (track_confidence IS NULL OR (track_confidence >= 0.0 AND track_confidence <= 1.0))

{
  "license_plates": [{"text": "ABC123", "confidence": 0.95}],
  "faces": [{"bbox": [10, 20, 100, 120], "embedding": [...]}],
  "clothing": {"upper_color": "blue", "lower_color": "black"},
  "vehicle": {"make": "Toyota", "model": "Camry", "color": "silver"},
  "weather": {"condition": "clear", "visibility": "good"},
  "image_quality": {"blur": 0.1, "brightness": 0.7}
}

# backend/models/detection.py:81-108
camera: Mapped[Camera]                      # Many-to-one
event_records: Mapped[list[EventDetection]] # Junction table records

# Enrichment result relationships
pose_result: Mapped[PoseResult | None]
threat_detections: Mapped[list[ThreatDetection]]
demographics_result: Mapped[DemographicsResult | None]
reid_embedding: Mapped[ReIDEmbedding | None]
action_result: Mapped[ActionResult | None]

# backend/models/enums.py
class Severity(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"

-- backend/models/event.py:211-222
CHECK (risk_level IS NULL OR risk_level IN ('low', 'medium', 'high', 'critical'))
CHECK (risk_score IS NULL OR (risk_score >= 0 AND risk_score <= 100))
CHECK (ended_at IS NULL OR ended_at >= started_at)

# backend/models/event.py:126-168
camera: Mapped[Camera]                          # Many-to-one
alerts: Mapped[list[Alert]]                     # One-to-many, cascade delete
audit: Mapped[EventAudit | None]                # One-to-one
detection_records: Mapped[list[EventDetection]] # Junction table records
feedback: Mapped[EventFeedback | None]          # One-to-one
detections: Mapped[list[Detection]]             # Many-to-many via junction

# backend/models/event.py:316-335
@property
def detection_id_list(self) -> list[int]:
    """Get list of detection IDs from the relationship."""
    return [d.id for d in self.detections]

@property
def detection_count(self) -> int:
    """Get count of detections associated with this event."""
    return len(self.detections)

# backend/models/event.py:341-397
@hybrid_property
def computed_risk_level(self) -> str | None:
    """Compute risk level from risk_score using configurable thresholds.

    Default thresholds:
    - 0-29: low
    - 30-59: medium
    - 60-84: high
    - 85-100: critical

    Returns:
        Risk level string ('low', 'medium', 'high', 'critical') or None if no risk_score
    """

# Python-side usage
event = await session.get(Event, event_id)
print(event.computed_risk_level)  # 'high'

# SQL-side usage (generates CASE expression)
from sqlalchemy import select
stmt = select(Event).where(Event.computed_risk_level == 'critical')

# backend/models/event_detection.py
event: Mapped[Event] = relationship("Event", back_populates="detection_records")
detection: Mapped[Detection] = relationship("Detection", back_populates="event_records")

ForeignKey("events.id", ondelete="CASCADE")
ForeignKey("detections.id", ondelete="CASCADE")

from backend.models.camera import Camera, normalize_camera_id

# Factory method (recommended)
camera = Camera.from_folder_name("Front Door", "/export/foscam/Front Door")
# camera.id = "front_door"
# camera.name = "Front Door"

# Direct creation
camera = Camera(
    id=normalize_camera_id("Back Yard"),
    name="Back Yard",
    folder_path="/export/foscam/Back Yard",
    status="online"
)

from backend.models.detection import Detection

detection = Detection(
    camera_id="front_door",
    file_path="/export/foscam/Front Door/image_001.jpg",
    file_type="image/jpeg",
    object_type="person",
    confidence=0.92,
    bbox_x=100, bbox_y=50, bbox_width=200, bbox_height=400
)

from backend.models.event import Event
from backend.models.event_detection import EventDetection

event = Event(
    batch_id="abc123-def456",
    camera_id="front_door",
    started_at=datetime.now(UTC),
    risk_score=75,
    risk_level="high",
    summary="Person detected at front door"
)

# Link detections via junction table
for detection_id in [1, 2, 3]:
    event.detection_records.append(
        EventDetection(detection_id=detection_id)
    )

from sqlalchemy import select
from sqlalchemy.orm import selectinload

# Eager load detections to avoid N+1
stmt = (
    select(Event)
    .options(selectinload(Event.detections))
    .where(Event.camera_id == "front_door")
    .order_by(Event.started_at.desc())
    .limit(10)
)

events = await session.execute(stmt)
for event in events.scalars():
    print(f"Event {event.id}: {event.detection_count} detections")