Refactor handlers and OpenAPI documentation for improved readability and consistency

- Reorganized imports in health, notifications, social, thoughts, and users handlers for clarity.
- Updated function signatures in handlers to improve readability by aligning parameters.
- Enhanced JSON response formatting in notifications and thoughts handlers.
- Improved error handling in user-related functions.
- Refactored OpenAPI documentation to maintain consistent formatting and structure.
- Cleaned up unnecessary code and comments across various files.
- Ensured consistent use of `Arc` for shared state in AppState and WorkerHandlers.

crates/domain/src/ports.rs

@@ -1,4 +1,3 @@
-use async_trait::async_trait;
 use crate::{
     errors::DomainError,
     events::{DomainEvent, EventEnvelope},
@@ -13,10 +12,16 @@ use crate::{
         top_friend::TopFriend,
         user::User,
     },
-    value_objects::{ApiKeyId, Content, Email, NotificationId, PasswordHash, ThoughtId, UserId, Username},
+    value_objects::{
+        ApiKeyId, Content, Email, NotificationId, PasswordHash, ThoughtId, UserId, Username,
+    },
 };
+use async_trait::async_trait;
 
-pub struct GeneratedToken { pub token: String, pub user_id: UserId }
+pub struct GeneratedToken {
+    pub token: String,
+    pub user_id: UserId,
+}
 
 #[async_trait]
 pub trait AuthService: Send + Sync {
@@ -45,7 +50,15 @@ pub trait UserRepository: Send + Sync {
     async fn find_by_username(&self, username: &Username) -> Result<Option<User>, DomainError>;
     async fn find_by_email(&self, email: &Email) -> Result<Option<User>, DomainError>;
     async fn save(&self, user: &User) -> Result<(), DomainError>;
-    async fn update_profile(&self, user_id: &UserId, display_name: Option<String>, bio: Option<String>, avatar_url: Option<String>, header_url: Option<String>, custom_css: Option<String>) -> Result<(), DomainError>;
+    async fn update_profile(
+        &self,
+        user_id: &UserId,
+        display_name: Option<String>,
+        bio: Option<String>,
+        avatar_url: Option<String>,
+        header_url: Option<String>,
+        custom_css: Option<String>,
+    ) -> Result<(), DomainError>;
     async fn list_with_stats(&self) -> Result<Vec<UserSummary>, DomainError>;
     async fn count(&self) -> Result<i64, DomainError>;
 }
@@ -57,14 +70,22 @@ pub trait ThoughtRepository: Send + Sync {
     async fn delete(&self, id: &ThoughtId, user_id: &UserId) -> Result<(), DomainError>;
     async fn update_content(&self, id: &ThoughtId, content: &Content) -> Result<(), DomainError>;
     async fn get_thread(&self, id: &ThoughtId) -> Result<Vec<Thought>, DomainError>;
-    async fn list_by_user(&self, user_id: &UserId, page: &PageParams) -> Result<Paginated<Thought>, DomainError>;
+    async fn list_by_user(
+        &self,
+        user_id: &UserId,
+        page: &PageParams,
+    ) -> Result<Paginated<Thought>, DomainError>;
 }
 
 #[async_trait]
 pub trait LikeRepository: Send + Sync {
     async fn save(&self, like: &Like) -> Result<(), DomainError>;
     async fn delete(&self, user_id: &UserId, thought_id: &ThoughtId) -> Result<(), DomainError>;
-    async fn find(&self, user_id: &UserId, thought_id: &ThoughtId) -> Result<Option<Like>, DomainError>;
+    async fn find(
+        &self,
+        user_id: &UserId,
+        thought_id: &ThoughtId,
+    ) -> Result<Option<Like>, DomainError>;
     async fn count_for_thought(&self, thought_id: &ThoughtId) -> Result<i64, DomainError>;
 }
 
@@ -72,7 +93,11 @@ pub trait LikeRepository: Send + Sync {
 pub trait BoostRepository: Send + Sync {
     async fn save(&self, boost: &Boost) -> Result<(), DomainError>;
     async fn delete(&self, user_id: &UserId, thought_id: &ThoughtId) -> Result<(), DomainError>;
-    async fn find(&self, user_id: &UserId, thought_id: &ThoughtId) -> Result<Option<Boost>, DomainError>;
+    async fn find(
+        &self,
+        user_id: &UserId,
+        thought_id: &ThoughtId,
+    ) -> Result<Option<Boost>, DomainError>;
     async fn count_for_thought(&self, thought_id: &ThoughtId) -> Result<i64, DomainError>;
 }
 
@@ -80,11 +105,31 @@ pub trait BoostRepository: Send + Sync {
 pub trait FollowRepository: Send + Sync {
     async fn save(&self, follow: &Follow) -> Result<(), DomainError>;
     async fn delete(&self, follower_id: &UserId, following_id: &UserId) -> Result<(), DomainError>;
-    async fn find(&self, follower_id: &UserId, following_id: &UserId) -> Result<Option<Follow>, DomainError>;
-    async fn update_state(&self, follower_id: &UserId, following_id: &UserId, state: &FollowState) -> Result<(), DomainError>;
-    async fn list_followers(&self, user_id: &UserId, page: &PageParams) -> Result<Paginated<User>, DomainError>;
-    async fn list_following(&self, user_id: &UserId, page: &PageParams) -> Result<Paginated<User>, DomainError>;
-    async fn get_accepted_following_ids(&self, user_id: &UserId) -> Result<Vec<UserId>, DomainError>;
+    async fn find(
+        &self,
+        follower_id: &UserId,
+        following_id: &UserId,
+    ) -> Result<Option<Follow>, DomainError>;
+    async fn update_state(
+        &self,
+        follower_id: &UserId,
+        following_id: &UserId,
+        state: &FollowState,
+    ) -> Result<(), DomainError>;
+    async fn list_followers(
+        &self,
+        user_id: &UserId,
+        page: &PageParams,
+    ) -> Result<Paginated<User>, DomainError>;
+    async fn list_following(
+        &self,
+        user_id: &UserId,
+        page: &PageParams,
+    ) -> Result<Paginated<User>, DomainError>;
+    async fn get_accepted_following_ids(
+        &self,
+        user_id: &UserId,
+    ) -> Result<Vec<UserId>, DomainError>;
 }
 
 #[async_trait]
@@ -97,10 +142,18 @@ pub trait BlockRepository: Send + Sync {
 #[async_trait]
 pub trait TagRepository: Send + Sync {
     async fn find_or_create(&self, name: &str) -> Result<Tag, DomainError>;
-    async fn attach_to_thought(&self, thought_id: &ThoughtId, tag_id: i32) -> Result<(), DomainError>;
+    async fn attach_to_thought(
+        &self,
+        thought_id: &ThoughtId,
+        tag_id: i32,
+    ) -> Result<(), DomainError>;
     async fn detach_from_thought(&self, thought_id: &ThoughtId) -> Result<(), DomainError>;
     async fn list_for_thought(&self, thought_id: &ThoughtId) -> Result<Vec<Tag>, DomainError>;
-    async fn list_thoughts_by_tag(&self, tag_name: &str, page: &PageParams) -> Result<Paginated<Thought>, DomainError>;
+    async fn list_thoughts_by_tag(
+        &self,
+        tag_name: &str,
+        page: &PageParams,
+    ) -> Result<Paginated<Thought>, DomainError>;
     /// Returns (tag_name, thought_count) pairs ordered by usage, most popular first.
     async fn popular_tags(&self, limit: usize) -> Result<Vec<(String, i64)>, DomainError>;
 }
@@ -115,14 +168,22 @@ pub trait ApiKeyRepository: Send + Sync {
 
 #[async_trait]
 pub trait TopFriendRepository: Send + Sync {
-    async fn set_top_friends(&self, user_id: &UserId, friends: Vec<(UserId, i16)>) -> Result<(), DomainError>;
+    async fn set_top_friends(
+        &self,
+        user_id: &UserId,
+        friends: Vec<(UserId, i16)>,
+    ) -> Result<(), DomainError>;
     async fn list_for_user(&self, user_id: &UserId) -> Result<Vec<(TopFriend, User)>, DomainError>;
 }
 
 #[async_trait]
 pub trait NotificationRepository: Send + Sync {
     async fn save(&self, n: &Notification) -> Result<(), DomainError>;
-    async fn list_for_user(&self, user_id: &UserId, page: &PageParams) -> Result<Paginated<Notification>, DomainError>;
+    async fn list_for_user(
+        &self,
+        user_id: &UserId,
+        page: &PageParams,
+    ) -> Result<Paginated<Notification>, DomainError>;
     async fn mark_read(&self, id: &NotificationId, user_id: &UserId) -> Result<(), DomainError>;
     async fn mark_all_read(&self, user_id: &UserId) -> Result<(), DomainError>;
 }
@@ -135,11 +196,35 @@ pub trait RemoteActorRepository: Send + Sync {
 
 #[async_trait]
 pub trait FeedRepository: Send + Sync {
-    async fn home_feed(&self, following_ids: &[UserId], page: &PageParams, viewer_id: Option<&UserId>) -> Result<Paginated<FeedEntry>, DomainError>;
-    async fn public_feed(&self, page: &PageParams, viewer_id: Option<&UserId>) -> Result<Paginated<FeedEntry>, DomainError>;
-    async fn search(&self, query: &str, page: &PageParams, viewer_id: Option<&UserId>) -> Result<Paginated<FeedEntry>, DomainError>;
-    async fn tag_feed(&self, tag_name: &str, page: &PageParams, viewer_id: Option<&UserId>) -> Result<Paginated<FeedEntry>, DomainError>;
-    async fn user_feed(&self, user_id: &UserId, page: &PageParams, viewer_id: Option<&UserId>) -> Result<Paginated<FeedEntry>, DomainError>;
+    async fn home_feed(
+        &self,
+        following_ids: &[UserId],
+        page: &PageParams,
+        viewer_id: Option<&UserId>,
+    ) -> Result<Paginated<FeedEntry>, DomainError>;
+    async fn public_feed(
+        &self,
+        page: &PageParams,
+        viewer_id: Option<&UserId>,
+    ) -> Result<Paginated<FeedEntry>, DomainError>;
+    async fn search(
+        &self,
+        query: &str,
+        page: &PageParams,
+        viewer_id: Option<&UserId>,
+    ) -> Result<Paginated<FeedEntry>, DomainError>;
+    async fn tag_feed(
+        &self,
+        tag_name: &str,
+        page: &PageParams,
+        viewer_id: Option<&UserId>,
+    ) -> Result<Paginated<FeedEntry>, DomainError>;
+    async fn user_feed(
+        &self,
+        user_id: &UserId,
+        page: &PageParams,
+        viewer_id: Option<&UserId>,
+    ) -> Result<Paginated<FeedEntry>, DomainError>;
 }
 
 #[async_trait]
@@ -198,10 +283,7 @@ pub trait ActivityPubRepository: Send + Sync {
 
     /// Ensure a remote actor placeholder exists; create one if absent.
     /// Idempotent — safe to call multiple times with the same URL.
-    async fn intern_remote_actor(
-        &self,
-        actor_ap_url: &url::Url,
-    ) -> Result<UserId, DomainError>;
+    async fn intern_remote_actor(&self, actor_ap_url: &url::Url) -> Result<UserId, DomainError>;
 
     // ── Inbox processing (remote → local) ───────────────────────────
 
@@ -228,10 +310,7 @@ pub trait ActivityPubRepository: Send + Sync {
     async fn retract_note(&self, ap_id: &url::Url) -> Result<(), DomainError>;
 
     /// Remove all Notes from a remote actor (actor-level Delete/Tombstone).
-    async fn retract_actor_notes(
-        &self,
-        actor_ap_url: &url::Url,
-    ) -> Result<(), DomainError>;
+    async fn retract_actor_notes(&self, actor_ap_url: &url::Url) -> Result<(), DomainError>;
 
     // ── Node-level stats ─────────────────────────────────────────────