refactor: improve variable naming and add comments for clarity in models and services

app/models/activity.py

@@ -11,7 +11,7 @@ from sqlalchemy import DateTime, ForeignKey, Integer, func, text
 from sqlalchemy import Enum as SqlEnum
 from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Mapped, mapped_column, relationship
-from sqlalchemy.types import JSON as GenericJSON
+from sqlalchemy.types import JSON as SA_JSON
 from sqlalchemy.types import TypeDecorator
 
 from app.models.base import Base, enum_values
@@ -33,9 +33,9 @@ class JSONBCompat(TypeDecorator):
 
     def load_dialect_impl(self, dialect):  # type: ignore[override]
         if dialect.name == "sqlite":
-            from sqlalchemy.dialects.sqlite import JSON as SQLiteJSON  # local import
+            from sqlalchemy.dialects.sqlite import JSON as SQLITE_JSON  # local import
 
-            return dialect.type_descriptor(SQLiteJSON())
+            return dialect.type_descriptor(SQLITE_JSON())
         return dialect.type_descriptor(JSONB())
 
 
@@ -55,7 +55,7 @@ class Activity(Base):
         nullable=False,
     )
     payload: Mapped[dict[str, Any]] = mapped_column(
-        JSONBCompat().with_variant(GenericJSON(), "sqlite"),
+        JSONBCompat().with_variant(SA_JSON(), "sqlite"),
         nullable=False,
         server_default=text("'{}'"),
     )

app/models/base.py

@@ -14,7 +14,7 @@ class Base(DeclarativeBase):
     """Base class that configures naming conventions."""
 
     @declared_attr.directive
-    def __tablename__(cls) -> str:  # type: ignore[misc]
+    def __tablename__(cls) -> str:  # type: ignore[misc]  # noqa: N805 - SQLAlchemy expects cls
         return cls.__name__.lower()
 
 

app/models/token.py

@@ -16,7 +16,7 @@ class TokenPayload(BaseModel):
 class TokenResponse(BaseModel):
     access_token: str
     refresh_token: str
-    token_type: str = "bearer"
+    token_type: str = "bearer"  # noqa: S105 -- OAuth2 spec default value
     expires_in: int
     refresh_expires_in: int