implement referral system

Author: cjustinobi

migrations/2026-04-11-150500_create_referral_system/down.sql

@@ -0,0 +1,12 @@
+-- Drop tables
+DROP TABLE IF EXISTS referral_rewards;
+DROP TABLE IF EXISTS referrals;
+DROP TABLE IF EXISTS app_configs;
+
+-- Remove columns from users
+ALTER TABLE users DROP COLUMN IF EXISTS referral_link;
+ALTER TABLE users DROP COLUMN IF EXISTS referral_code;
+
+-- Drop enums
+DROP TYPE IF EXISTS reward_type;
+DROP TYPE IF EXISTS referral_status;

migrations/2026-04-11-150500_create_referral_system/up.sql

@@ -0,0 +1,59 @@
+-- Create ENUM types for referral system
+CREATE TYPE referral_status AS ENUM ('pending', 'active', 'verified');
+CREATE TYPE reward_type AS ENUM ('earned', 'applied');
+
+-- Modify users table
+ALTER TABLE users ADD COLUMN referral_code VARCHAR(50) UNIQUE;
+ALTER TABLE users ADD COLUMN referral_link TEXT;
+
+-- Generate random referral codes for existing users (8 chars)
+UPDATE users SET referral_code = UPPER(SUBSTR(MD5(id::text), 1, 8)) WHERE referral_code IS NULL;
+
+-- Make referral_code NOT NULL after backfilling
+ALTER TABLE users ALTER COLUMN referral_code SET NOT NULL;
+
+-- Create app_configs table
+CREATE TABLE app_configs (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    key VARCHAR(100) UNIQUE NOT NULL,
+    value TEXT NOT NULL,
+    description TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Seed default configs
+INSERT INTO app_configs (key, value, description) VALUES 
+('reward_point', '100', 'The Naira equivalent of 1 reward point'),
+('referral_points_patient', '1', 'Points earned for referring a patient'),
+('referral_points_donor', '1', 'Points earned for referring a donor'),
+('referral_points_specialist', '1', 'Points earned for referring a specialist'),
+('referral_points_hospital', '1', 'Points earned for referring a hospital');
+
+-- Create referrals table
+CREATE TABLE referrals (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    referrer_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    referred_user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    referral_code VARCHAR(50) NOT NULL, -- The code used during registration
+    status referral_status NOT NULL DEFAULT 'pending',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    UNIQUE(referrer_id, referred_user_id)
+);
+
+-- Create referral_rewards table
+CREATE TABLE referral_rewards (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    referral_id UUID REFERENCES referrals(id) ON DELETE SET NULL, -- Optional if not linked to a specific referral (e.g. bonus)
+    points INT4 NOT NULL,
+    reward_type reward_type NOT NULL,
+    description TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Indexes
+CREATE INDEX idx_users_referral_code ON users(referral_code);
+CREATE INDEX idx_referrals_referrer_id ON referrals(referrer_id);
+CREATE INDEX idx_referrals_referred_user_id ON referrals(referred_user_id);
+CREATE INDEX idx_referral_rewards_user_id ON referral_rewards(user_id);

src/admin/dtos.rs

@@ -235,3 +235,17 @@ pub enum AdminUserProfileResponse {
     #[serde(rename = "hospital")]
     Hospital(AdminHospitalProfileResponse),
 }
+
+#[derive(Debug, Deserialize, ToSchema)]
+pub struct ConfigActionRequest {
+    pub value: String,
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Serialize, ToSchema)]
+pub struct ConfigResponse {
+    pub key: String,
+    pub value: String,
+    pub description: Option<String>,
+    pub updated_at: DateTime<Utc>,
+}

src/auth/service.rs

@@ -68,6 +68,9 @@ pub fn create_user(
     }
 
     // ---- Insert new user ----
+    // I'll use random bytes for an 8-character hex code.
+    let random_code = format!("{:08X}", OsRng.next_u32());
+
     let new_user = NewUser {
         first_name: "",
         last_name: "",
@@ -80,6 +83,8 @@ pub fn create_user(
         password_hash: &hashed_password,
         role: user_role,
         consultation_preference: None,
+        referral_code: &random_code,
+        referral_link: None,
     };
 
     let user = diesel::insert_into(users)

src/auth/socials.rs

@@ -41,6 +41,7 @@ pub fn login_or_register_social_user(
         Some(u) => u,
         None => {
             // 3. Create new user
+            let referral_code = format!("{:08X}", rand::random::<u32>());
             let new_user = NewUser {
                 first_name: profile.first_name.as_deref().unwrap_or(""),
                 last_name: profile.last_name.as_deref().unwrap_or(""),
@@ -53,6 +54,8 @@ pub fn login_or_register_social_user(
                 password_hash: "", // IMPORTANT: no password
                 role: role.unwrap_or(Role::Patient),
                 consultation_preference: None,
+                referral_code: &referral_code,
+                referral_link: None,
             };
 
             diesel::insert_into(users::table)

src/bin/seed.rs

@@ -61,6 +61,8 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         password_hash: &password_hash,
         role: Role::Patient,
         consultation_preference: None,
+        referral_code: "PATIENT1",
+        referral_link: None,
     };
 
     diesel::insert_into(users::table)
@@ -109,6 +111,8 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         password_hash: &password_hash,
         role: Role::Donor,
         consultation_preference: None,
+        referral_code: "DONOR123",
+        referral_link: None,
     };
 
     diesel::insert_into(users::table)
@@ -157,6 +161,8 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         password_hash: &password_hash,
         role: Role::Hospital,
         consultation_preference: None,
+        referral_code: "HOSPITAL",
+        referral_link: None,
     };
 
     diesel::insert_into(users::table)
@@ -187,6 +193,8 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         password_hash: &password_hash,
         role: Role::Admin,
         consultation_preference: None,
+        referral_code: "ADMIN123",
+        referral_link: None,
     };
 
     diesel::insert_into(users::table)
@@ -217,6 +225,8 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         password_hash: &password_hash,
         role: Role::Specialist,
         consultation_preference: None,
+        referral_code: "DRSARAH1",
+        referral_link: None,
     };
 
     diesel::insert_into(users::table)

src/docs.rs

@@ -1,5 +1,5 @@
 use crate::handlers::{
-    admin, appointments, auth, common, hospitals, notifications, patients, socials, specialists,
+    admin, appointments, auth, common, hospitals, notifications, patients, referrals, socials, specialists,
 };
 use utoipa::OpenApi;
 use utoipa::openapi::security::{HttpAuthScheme, HttpBuilder, SecurityScheme};
@@ -72,9 +72,29 @@ use utoipa::openapi::security::{HttpAuthScheme, HttpBuilder, SecurityScheme};
         admin::get_users,
         admin::update_specialist_status,
         admin::update_hospital_status,
+        admin::update_app_config,
+        referrals::get_referral_summary,
+        referrals::update_referral_link,
     ),
 
-    components(),
+    components(
+        schemas(
+            referrals::ReferralSummaryResponse,
+            referrals::RewardHistoryResponse,
+            referrals::ReferralStat,
+            referrals::UpdateReferralLinkPayload,
+            auth::RegisterRequest,
+            auth::LoginRequest,
+            auth::AuthResponse,
+            auth::UserResponse,
+            crate::admin::dtos::ConfigActionRequest,
+            crate::admin::dtos::ConfigResponse,
+            crate::utils::enums::ReferralStatusEnum,
+            crate::utils::enums::RewardTypeEnum,
+            crate::utils::enums::Role,
+            crate::utils::enums::ConsultationTypeEnum,
+        )
+    ),
 
     modifiers(&SecurityAddon),
     tags(
@@ -86,6 +106,7 @@ use utoipa::openapi::security::{HttpAuthScheme, HttpBuilder, SecurityScheme};
         (name = "notifications", description = "Notification management endpoints"),
         (name = "settings", description = "User settings endpoints"),
         (name = "admin", description = "Admin management endpoints"),
+        (name = "referrals", description = "Referral system endpoints"),
     ),
     info(
         title = "RubiMedik API",

src/handlers/admin.rs

@@ -10,8 +10,9 @@ use crate::{
         },
         dashboard,
         dtos::{
-            AdminDashboardResponse, HospitalActionRequest, SpecialistActionRequest, UserFilters,
-            UserListResponse, AdminPatientProfileResponse, AdminUserProfileResponse,
+            AdminDashboardResponse, ConfigActionRequest, ConfigResponse, HospitalActionRequest,
+            SpecialistActionRequest, UserFilters, UserListResponse, AdminPatientProfileResponse,
+            AdminUserProfileResponse,
         },
     },
     error::AppError,
@@ -278,3 +279,55 @@ pub async fn get_user_profile(
 
     Ok(ApiResponse::success(response))
 }
+
+/// Update application configuration (Admin only)
+///
+/// Allows admins to update system-wide settings like reward points and conversion rates
+#[utoipa::path(
+    put,
+    path = "/api/admin/configs/{key}",
+    request_body = ConfigActionRequest,
+    responses(
+        (status = 200, body = ApiResponse<ConfigResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Forbidden - Admin only"),
+        (status = 404, description = "Config key not found"),
+        (status = 500)
+    ),
+    tag = "admin",
+    security(("bearer_auth" = []))
+)]
+pub async fn update_app_config(
+    State(state): State<AppState>,
+    Extension(current_admin): Extension<User>,
+    Path(key): Path<String>,
+    Json(payload): Json<crate::admin::dtos::ConfigActionRequest>,
+) -> Result<ApiResponse<crate::admin::dtos::ConfigResponse>, AppError> {
+    use crate::schema::app_configs;
+    use diesel::prelude::*;
+
+    // Ensure user is admin
+    if !matches!(current_admin.role, crate::utils::enums::Role::Admin) {
+        return Err(AppError::Unauthorized(
+            "Only administrators can perform this action".into(),
+        ));
+    }
+
+    let mut conn = state.pool.get()?;
+
+    let updated_config = diesel::update(app_configs::table.filter(app_configs::key.eq(&key)))
+        .set((
+            app_configs::value.eq(payload.value),
+            app_configs::description.eq(payload.description),
+            app_configs::updated_at.eq(chrono::Utc::now()),
+        ))
+        .get_result::<crate::models::AppConfig>(&mut conn)
+        .map_err(|_| AppError::NotFound(format!("Config key '{}' not found", key)))?;
+
+    Ok(ApiResponse::success(crate::admin::dtos::ConfigResponse {
+        key: updated_config.key,
+        value: updated_config.value,
+        description: updated_config.description,
+        updated_at: updated_config.updated_at,
+    }))
+}

src/handlers/auth.rs

@@ -21,7 +21,7 @@ pub struct RegisterRequest {
     pub email: String,
     pub password: String,
     pub role: String,
-    // pub phone: Option<String>,
+    pub referred_by_code: Option<String>,
 }
 
 #[derive(Deserialize, ToSchema)]
@@ -78,6 +78,8 @@ pub struct UserResponse {
     pub email: String,
     pub role: String,
     pub consultation_preference: Option<ConsultationTypeEnum>,
+    pub referral_code: String,
+    pub referral_link: Option<String>,
 }
 
 #[derive(Serialize, ToSchema)]
@@ -95,6 +97,8 @@ impl From<User> for UserResponse {
             email: user.email,
             role: user.role.to_string(),
             consultation_preference: user.consultation_preference,
+            referral_code: user.referral_code,
+            referral_link: user.referral_link,
         }
     }
 }
@@ -155,7 +159,35 @@ pub async fn register(
         }
     }
 
-    let user = auth::create_user(&mut conn, &payload.email, &payload.password, other_role)?;
+    let user = conn.transaction::<User, AppError, _>(|conn| {
+        let new_user = auth::create_user(conn, &payload.email, &payload.password, other_role)?;
+
+        // Handle referral
+        if let Some(ref_code) = &payload.referred_by_code {
+            if let Some(referrer) = users
+                .filter(crate::schema::users::referral_code.eq(ref_code))
+                .first::<User>(conn)
+                .optional()?
+            {
+                use crate::schema::referrals;
+                use crate::models::NewReferral;
+                use crate::utils::enums::ReferralStatusEnum;
+
+                let new_referral = NewReferral {
+                    referrer_id: referrer.id,
+                    referred_user_id: new_user.id,
+                    referral_code: ref_code.clone(),
+                    status: ReferralStatusEnum::Pending,
+                };
+
+                diesel::insert_into(referrals::table)
+                    .values(&new_referral)
+                    .execute(conn)?;
+            }
+        }
+
+        Ok(new_user)
+    })?;
 
     let code = auth::create_email_verification_code(&mut conn, user.id, 4)?;
 

src/handlers/mod.rs

@@ -6,4 +6,5 @@ pub mod appointments;
 pub mod notifications;
 pub mod socials;
 pub mod common;
-pub mod admin;
+pub mod admin;
+pub mod referrals;