feat: implement persistent bot mode and update docs

Author: cliff-de-tech

README.md

@@ -107,6 +107,28 @@ It's built for developers who want to grow their professional presence without s
 
 ---
 
+## 🆕 Recent Updates (January 2026)
+
+### Persistent Bot Mode 🤖
+
+- **Auto-Save Drafts**: Generated posts are immediately saved to the database as drafts, preventing data loss on refresh.
+- **Historical Stats**: "Generated" and "Published" counts now reflect all-time history, not just the current session.
+- **Smart Publishing**: Publishing updates existing drafts instead of creating duplicates.
+
+### Enhanced Analytics 📊
+
+- **Real-Time Accuracy**: Dashboard stats now accurately reflect live counts for Published, Draft, and Scheduled posts.
+- **Growth Metrics**: Dynamic week-over-week growth percentages and "Published This Month" tracking.
+- **Visual Improvements**: New "Scheduled" stats card and updated "Generated" vs "Published" cards.
+
+### Post Scheduling 📅
+
+- **Schedule for Later**: Ability to schedule posts for future publication dates.
+- **Background Processing**: Powered by Celery and Redis for reliable timely delivery.
+- **Management**: View and manage scheduled posts directly from the history view.
+
+---
+
 ## Security & LinkedIn Compliance
 
 This project prioritizes **safety and compliance**:
@@ -671,7 +693,7 @@ celery -A services.celery_app worker --loglevel=info
 celery -A services.celery_app beat --loglevel=info
 ```
 
-> **Note**: For local development without Redis, scheduled posts will not auto-publish. 
+> **Note**: For local development without Redis, scheduled posts will not auto-publish.
 > The full Docker stack (`make up`) is recommended for testing scheduled functionality.
 
 Open [http://localhost:3000](http://localhost:3000) to access the dashboard.

backend/repositories/posts.py

@@ -102,6 +102,38 @@ async def get_stats(self) -> Dict:
                 stats['total'] += count
 
         return stats
+
+    async def get_bot_stats(self) -> Dict:
+        """
+        Get aggregated statistics for bot-generated posts.
+        
+        Returns:
+            Dictionary with generated and published counts
+        """
+        query = """
+            SELECT 
+                status,
+                COUNT(*) as count
+            FROM post_history
+            WHERE user_id = $1 AND post_type = 'bot'
+            GROUP BY status
+        """
+        result = await self.db.fetch_all(query, [self.user_id])
+        
+        stats = {
+            'generated': 0,
+            'published': 0
+        }
+        
+        if result:
+            for row in result:
+                status = row['status']
+                count = row['count']
+                stats['generated'] += count  # All bot posts count as generated
+                if status == 'published':
+                    stats['published'] += count
+        
+        return stats
 
     async def save_post(
         self,

backend/routes/posts.py

@@ -69,6 +69,11 @@
     get_access_token_for_urn = None
     get_token_by_user_id = None
 
+try:
+    from services.scheduled_posts import schedule_post
+except ImportError:
+    schedule_post = None
+
 try:
     from services.auth_service import (
         TokenNotFoundError,
@@ -91,11 +96,17 @@
     post_generation_limiter = None
     publish_limiter = None
 
+try:
+    from middleware.clerk_auth import get_current_user
+except ImportError:
 try:
     from middleware.clerk_auth import get_current_user
 except ImportError:
     get_current_user = None
 
+from services.db import get_database
+from repositories.posts import PostRepository
+
 
 # =============================================================================
 # REQUEST MODELS
@@ -114,6 +125,13 @@ class PostRequest(BaseModel):
     model: Optional[str] = "groq"
 
 
+class ScheduleRequest(BaseModel):
+    user_id: str
+    post_content: str
+    scheduled_time: int
+    image_url: Optional[str] = None
+
+
 class BatchGenerateRequest(BaseModel):
     """Request for batch post generation in Bot Mode."""
     user_id: str
@@ -292,15 +310,32 @@ async def generate_batch(req: BatchGenerateRequest):
                 )
 
                 if result:
-                    generated_posts.append({
+                    final_post = {
                         "id": f"gen_{success_count}_{activity.get('id', '')}",
                         "content": result.content,
                         "activity": activity,
                         "style": style,
                         "status": "draft",
                         "provider": result.provider.value,
                         "model": result.model,
-                    })
+                    }
+                    generated_posts.append(final_post)
+                    
+                    # PERSISTENCE: Save as draft immediately
+                    try:
+                        db = get_database()
+                        repo = PostRepository(db, req.user_id)
+                        saved_id = await repo.save_post(
+                            post_content=result.content,
+                            post_type='bot',
+                            context=activity,
+                            status='draft'
+                        )
+                        final_post['id'] = str(saved_id)
+                        final_post['db_id'] = saved_id
+                    except Exception as e:
+                        logger.error("failed_to_persist_post_provider", error=str(e))
+                        
                     used_provider = result.provider.value
                     was_downgraded = result.was_downgraded
                     success_count += 1
@@ -315,22 +350,47 @@ async def generate_batch(req: BatchGenerateRequest):
                 )
 
                 if post_content:
-                    generated_posts.append({
+                    final_post = {
                         "id": f"gen_{success_count}_{activity.get('id', '')}",
                         "content": post_content,
                         "activity": activity,
                         "style": style,
                         "status": "draft",
                         "provider": "groq",
                         "model": "llama-3.3-70b-versatile",
-                    })
+                    }
+                    generated_posts.append(final_post)
+                    
+                    # PERSISTENCE: Save as draft immediately
+                    try:
+                        db = get_database()
+                        repo = PostRepository(db, req.user_id)
+                        saved_id = await repo.save_post(
+                            post_content=post_content,
+                            post_type='bot',
+                            context=activity,
+                            status='draft'
+                        )
+                        # Build full object with real ID so frontend can use it for publishing
+                        final_post['id'] = str(saved_id)
+                        final_post['db_id'] = saved_id  # explicitly track DB ID
+                    except Exception as e:
+                        logger.error("failed_to_persist_post", error=str(e))
+                        
                     success_count += 1
                 else:
                     failed_count += 1
 
         except Exception as e:
             logger.error("failed_to_generate_post", error=str(e))
             failed_count += 1
+            
+    # For provider-based generation loop above, we also need persistence
+    # (Note: I'm patching the loop above in a second chunk or assuming the user meant to cover both paths. 
+    # To be safe and clean, I will wrap the persistence logic in a helper or duplicate it for the first branch if I can't easily merge.)
+    # Actually, the previous 'if result:' block also needs persistence. 
+    # Let me re-read the file content to ensure I catch both branches.
+    # The file view showed headers 300-450.
 
     return {
         "posts": generated_posts,
@@ -342,6 +402,24 @@ async def generate_batch(req: BatchGenerateRequest):
     }
 
 
+@router.get("/bot-stats")
+async def get_bot_stats(
+    user_id: str,
+    current_user: dict = Depends(get_current_user) if get_current_user else None
+):
+    """Get statistics for bot mode (generated vs published)."""
+    if current_user and current_user.get("user_id") != user_id:
+         raise HTTPException(status_code=403, detail="Unauthorized")
+         
+    try:
+        db = get_database()
+        repo = PostRepository(db, user_id)
+        return await repo.get_bot_stats()
+    except Exception as e:
+        logger.error("failed_to_get_bot_stats", error=str(e))
+        return {"generated": 0, "published": 0}
+
+
 @router.get("/providers")
 async def list_providers(
     current_user: dict = Depends(get_current_user) if get_current_user else None
@@ -504,3 +582,23 @@ async def publish(req: PostRequest):
     if post_to_linkedin:
         post_to_linkedin(post, image_asset)
     return {"status": "posted", "post": post, "image_asset": image_asset}
+
+
+@router.post("/schedule")
+async def schedule(req: ScheduleRequest):
+    """Schedule a post for later publishing."""
+    if not schedule_post:
+        raise HTTPException(status_code=500, detail="Schedule service not available")
+
+    result = await schedule_post(
+        user_id=req.user_id,
+        post_content=req.post_content,
+        scheduled_time=req.scheduled_time,
+        image_url=req.image_url
+    )
+    
+    if not result.get("success"):
+        raise HTTPException(status_code=400, detail=result.get("error"))
+        
+    return result
+