chore: document project-wide soft delete pattern and add deleted_by column to all tables

devplacepy/routers/follow.py

@@ -3,7 +3,7 @@
 import logging
 from datetime import datetime, timezone
 from fastapi import APIRouter, Request
-from devplacepy.database import get_table
+from devplacepy.database import get_table, _now_iso
 from devplacepy.utils import (
     generate_uid,
     require_user,
@@ -28,17 +28,23 @@ async def follow_user(request: Request, username: str):
 
     follows = get_table("follows")
     existing = follows.find_one(follower_uid=user["uid"], following_uid=target["uid"])
-    if existing:
+    if existing and not existing.get("deleted_at"):
         return action_result(request, f"/profile/{username}")
-
-    follows.insert(
-        {
-            "uid": generate_uid(),
-            "follower_uid": user["uid"],
-            "following_uid": target["uid"],
-            "created_at": datetime.now(timezone.utc).isoformat(),
-        }
-    )
+    if existing:
+        follows.update(
+            {"id": existing["id"], "deleted_at": None, "deleted_by": None}, ["id"]
+        )
+    else:
+        follows.insert(
+            {
+                "uid": generate_uid(),
+                "follower_uid": user["uid"],
+                "following_uid": target["uid"],
+                "created_at": datetime.now(timezone.utc).isoformat(),
+                "deleted_at": None,
+                "deleted_by": None,
+            }
+        )
 
     create_notification(
         target["uid"],
@@ -72,9 +78,14 @@ async def unfollow_user(request: Request, username: str):
         return action_result(request, f"/profile/{username}")
 
     follows = get_table("follows")
-    existing = follows.find_one(follower_uid=user["uid"], following_uid=target["uid"])
+    existing = follows.find_one(
+        follower_uid=user["uid"], following_uid=target["uid"], deleted_at=None
+    )
     if existing:
-        follows.delete(id=existing["id"])
+        follows.update(
+            {"id": existing["id"], "deleted_at": _now_iso(), "deleted_by": user["uid"]},
+            ["id"],
+        )
         logger.info(f"{user['username']} unfollowed {username}")
         audit.record(
             request,