feat: database-first refactor, unified architecture and visual developer manual

Summary of changes:
- Consolidated Studio+CMS and Experience+LMS into unified services.
- Moved core business logic (enrollment, grading, auth) to PostgreSQL functions.
- Implemented advanced auditing via DB triggers and session context.
- Added gamification (XP/Levels/Leaderboards) and logic encapsulation.
- Updated installation/diagnostic scripts for the new architecture.
- Created a comprehensive Visual Developer Manual in README.md with hardware scaling.

shared/common/src/lib.rs

@@ -1,4 +1,5 @@
-pub mod models;
 pub mod auth;
-pub mod utils;
 pub mod middleware;
+pub mod models;
+pub mod utils;
+pub mod webhooks;

shared/common/src/models.rs

@@ -185,6 +185,36 @@ pub struct LessonAnalytics {
     pub average_score: f32, // 0.0-1.0
     pub submission_count: i64,
 }
+#[derive(Debug, Clone, Serialize, Deserialize, sqlx::FromRow)]
+pub struct CohortData {
+    pub period: String,
+    pub count: i64,
+    pub completion_rate: f32,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, sqlx::FromRow)]
+pub struct RetentionData {
+    pub lesson_id: Uuid,
+    pub lesson_title: String,
+    pub student_count: i64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AdvancedAnalytics {
+    pub cohorts: Vec<CohortData>,
+    pub retention: Vec<RetentionData>,
+}
+#[derive(Debug, Serialize, Deserialize, sqlx::FromRow, Clone)]
+pub struct Webhook {
+    pub id: Uuid,
+    pub organization_id: Uuid,
+    pub url: String,
+    pub events: Vec<String>,
+    pub secret: Option<String>,
+    pub is_active: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
 
 #[cfg(test)]
 mod tests {

shared/common/src/webhooks.rs

@@ -0,0 +1,84 @@
+use crate::models::Webhook;
+use hmac::{Hmac, Mac};
+use sha2::Sha256;
+use sqlx::PgPool;
+use uuid::Uuid;
+
+pub struct WebhookService {
+    pool: PgPool,
+}
+
+impl WebhookService {
+    pub fn new(pool: PgPool) -> Self {
+        Self { pool }
+    }
+
+    pub async fn dispatch(&self, org_id: Uuid, event_type: &str, payload: &serde_json::Value) {
+        let webhooks = match sqlx::query_as::<_, Webhook>(
+            "SELECT * FROM webhooks WHERE organization_id = $1 AND is_active = TRUE AND $2 = ANY(events)"
+        )
+        .bind(org_id)
+        .bind(event_type)
+        .fetch_all(&self.pool)
+        .await {
+            Ok(w) => w,
+            Err(e) => {
+                tracing::error!("Failed to fetch webhooks for org {}: {}", org_id, e);
+                return;
+            }
+        };
+
+        if webhooks.is_empty() {
+            return;
+        }
+
+        let client = reqwest::Client::new();
+        let payload_str = payload.to_string();
+
+        for webhook in webhooks {
+            let mut request = client
+                .post(&webhook.url)
+                .header("Content-Type", "application/json")
+                .header("X-OpenCCB-Event", event_type)
+                .header("X-OpenCCB-Delivery", Uuid::new_v4().to_string());
+
+            if let Some(secret) = &webhook.secret {
+                let signature = generate_signature(secret, &payload_str);
+                request = request.header("X-OpenCCB-Signature", signature);
+            }
+
+            let url = webhook.url.clone();
+            let res = request.body(payload_str.clone()).send().await;
+
+            match res {
+                Ok(response) => {
+                    if !response.status().is_success() {
+                        tracing::warn!(
+                            "Webhook delivery to {} (event: {}) failed with status {}",
+                            url,
+                            event_type,
+                            response.status()
+                        );
+                    }
+                }
+                Err(e) => {
+                    tracing::error!(
+                        "Failed to deliver webhook to {} (event: {}): {}",
+                        url,
+                        event_type,
+                        e
+                    );
+                }
+            }
+        }
+    }
+}
+
+fn generate_signature(secret: &str, payload: &str) -> String {
+    type HmacSha256 = Hmac<Sha256>;
+    let mut mac =
+        HmacSha256::new_from_slice(secret.as_bytes()).expect("HMAC can take key of any size");
+    mac.update(payload.as_bytes());
+    let result = mac.finalize();
+    hex::encode(result.into_bytes())
+}