semantic clean up

backend/src/models/config.py

@@ -1,10 +1,12 @@
 # [DEF:backend.src.models.config:Module]
 #
-# @TIER: STANDARD
-# @SEMANTICS: database, config, settings, sqlalchemy
-# @PURPOSE:   Defines database schema for persisted application configuration.
-# @LAYER:     Domain
-# @RELATION:  DEPENDS_ON -> sqlalchemy
+# @TIER: CRITICAL
+# @SEMANTICS: database, config, settings, sqlalchemy, notification
+# @PURPOSE: Defines SQLAlchemy persistence models for application and notification configuration records.
+# @LAYER: Domain
+# @RELATION: [DEPENDS_ON] ->[sqlalchemy]
+# @RELATION: [DEPENDS_ON] ->[backend.src.models.mapping:Base]
+# @INVARIANT: Configuration payload and notification credentials must remain persisted as non-null JSON documents.
 
 from sqlalchemy import Column, String, DateTime, JSON, Boolean
 from sqlalchemy.sql import func
@@ -13,7 +15,11 @@ from .mapping import Base
 
 
 # [DEF:AppConfigRecord:Class]
-# @PURPOSE: Stores the single source of truth for application configuration.
+# @PURPOSE: Stores persisted application configuration as a single authoritative record model.
+# @PRE: SQLAlchemy declarative Base is initialized and table metadata registration is active.
+# @POST: ORM table 'app_configurations' exposes id, payload, and updated_at fields with declared nullability/default semantics.
+# @SIDE_EFFECT: Registers ORM mapping metadata during module import.
+# @DATA_CONTRACT: Input -> persistence row {id:str, payload:json, updated_at:datetime}; Output -> AppConfigRecord ORM entity.
 class AppConfigRecord(Base):
     __tablename__ = "app_configurations"
 
@@ -25,7 +31,11 @@ class AppConfigRecord(Base):
 # [/DEF:AppConfigRecord:Class]
 
 # [DEF:NotificationConfig:Class]
-# @PURPOSE: Global settings for external notification providers.
+# @PURPOSE: Stores persisted provider-level notification configuration and encrypted credentials metadata.
+# @PRE: SQLAlchemy declarative Base is initialized and uuid generation is available at instance creation time.
+# @POST: ORM table 'notification_configs' exposes id, type, name, credentials, is_active, created_at, updated_at fields with declared constraints/defaults.
+# @SIDE_EFFECT: Registers ORM mapping metadata during module import; may generate UUID values for new entity instances.
+# @DATA_CONTRACT: Input -> persistence row {id:str, type:str, name:str, credentials:json, is_active:bool, created_at:datetime, updated_at:datetime}; Output -> NotificationConfig ORM entity.
 class NotificationConfig(Base):
     __tablename__ = "notification_configs"
 

backend/src/models/mapping.py

@@ -80,6 +80,8 @@ class MigrationJob(Base):
     status = Column(SQLEnum(MigrationStatus), default=MigrationStatus.PENDING)
     replace_db = Column(Boolean, default=False)
     created_at = Column(DateTime(timezone=True), server_default=func.now())
+# [/DEF:MigrationJob:Class]
+
 # [DEF:ResourceMapping:Class]
 # @TIER: STANDARD
 # @PURPOSE: Maps a universal UUID for a resource to its actual ID on a specific environment.