BioLink Pro Documentation

1. Overview & Architecture

BioLink Pro is an enterprise-grade bio-link and digital card management SaaS platform built with high performance, strict typing, and clean separation of concerns:

Core Directory Structure

2. System Requirements

Ensure your hosting environment meets the following specifications before installing BioLink Pro:

Mandatory PHP Extensions

The following extensions must be enabled in your php.ini:

3. File & Folder Permissions (Critical Guide)

Correct file permissions and user ownership are required for both platform security and operational reliability. Incorrect permissions will prevent file uploads, cache generation, or installer execution.

Baseline Unix Permissions

Mandatory Writable Directories

The following paths must be writable by the web server user (e.g. www-data, nginx, or your cPanel username):

Applying Permissions via Terminal / SSH

On an Ubuntu / Debian VPS with Nginx or Apache, run the following commands in your website root:

# 1. Set web server ownership (replace www-data with your web user if needed)
sudo chown -R www-data:www-data /var/www/biolink/public_html

# 2. Reset standard baseline permissions
sudo find /var/www/biolink/public_html -type d -exec chmod 755 {} \;
sudo find /var/www/biolink/public_html -type f -exec chmod 644 {} \;

# 3. Grant write permissions to designated storage and cache paths
sudo chmod -R 775 /var/www/biolink/public_html/uploads
sudo chmod -R 775 /var/www/biolink/public_html/api/cache
sudo chmod -R 775 /var/www/biolink/public_html/api/logs
sudo chmod 775 /var/www/biolink/public_html/install

# 4. Lock down sensitive environment configuration
sudo chmod 600 /var/www/biolink/public_html/.env

Applying Permissions via cPanel / DirectAdmin

• Log into cPanel and open File Manager.
• Navigate to public_html.
• Right-click on the uploads folder, select Change Permissions, and verify it is set to 755 (or 775 if required by your host). Repeat for api/cache and api/logs.
• Ensure the .htaccess file is visible (enable Show Hidden Files in File Manager settings).

4. Web GUI Installation Wizard

BioLink Pro features a streamlined web-based installation wizard that inspects your environment, validates database connectivity, imports seeds, and creates the primary administrator account.

1. Upload and Extract Package

   Upload biolink_pro_v1.3.0_fresh.zip (or biolink_pro_install_latest.zip) to your server's root directory (e.g. public_html) and extract all files.

2. Create Database

   In your hosting control panel (cPanel, Plesk, or phpMyAdmin), create a fresh MySQL database, create a database user with a strong password, and grant ALL PRIVILEGES to the user on that database.

3. Launch Installer

   Open your web browser and navigate to: https://yourdomain.com/install

4. System & Permission Check

   The installer automatically audits required PHP extensions and writable directory permissions. If any row is highlighted in red, apply the recommended permission and click Check Again.

5. Database Configuration

   Input your database parameters:

   • Host: 127.0.0.1 or localhost
   • Port: 3306
   • Database Name: Your created database name
   • Username & Password: Database credentials
6. System & Administrator Account

   Define your Application URL (e.g. https://yourdomain.com), site title, admin email, and secure password.

7. Complete & Automatic Lock

   Click Install BioLink Pro. The wizard executes the sanitized schema import, writes the .env file, sets up default themes and languages, and creates install/install.lock to secure against replay.

5. Manual Setup (CLI / VPS)

For DevOps engineers and automated containerized deployments, BioLink Pro can be initialized entirely via command line:

# 1. Extract package into your web root
cd /var/www/biolink/public_html
unzip -q biolink_pro_v1.3.0_fresh.zip

# 2. Import sanitized database seed into MySQL
mysql -u your_user -p your_database < install/install.sql

# 3. Create .env from template
cp .env.example .env

# 4. Configure .env with your credentials
nano .env

# Ensure DB_HOST, DB_NAME, DB_USER, DB_PASS, and APP_URL are set:
# DB_HOST=127.0.0.1
# DB_NAME=biolink_db
# DB_USER=biolink_user
# DB_PASS=SecretPassword123!
# APP_URL=https://yourdomain.com
# JWT_SECRET=GENERATE_A_64_CHAR_RANDOM_HEX_KEY

# 5. Lock installer directory
touch install/install.lock

# 6. Apply permissions
chown -R www-data:www-data /var/www/biolink/public_html
chmod 600 .env

6. Pre-Flight Verification Tool

BioLink Pro includes an automated environment verification script. Run this via CLI at any time to validate your configuration:

php tools/check_env.php

The tool outputs an audit of:

• PHP engine version compliance (>= 8.1).
• Active status of all required extensions.
• Live database ping and latency test.
• Storage permissions for uploads/, api/cache/, and api/logs/.
• Critical environment variable checks.

7. Automated Cron Jobs

BioLink Pro requires cron execution to perform automated queue dispatching, social media planner publishing, sitemap regeneration, and subscription renewals.

Crontab Configuration

Open your server crontab via crontab -e (or cPanel Cron Jobs):

# 1. High-frequency queue & scheduled social post publishing (Every 1 minute)
* * * * * curl -s "https://yourdomain.com/api/cron/run?token=YOUR_CRON_SECRET" > /dev/null 2>&1

# 2. Daily housekeeping, sitemap generation & expired plan processing (Daily at Midnight)
0 0 * * * curl -s "https://yourdomain.com/api/cron/daily?token=YOUR_CRON_SECRET" > /dev/null 2>&1

# 3. Database backup routine (Daily at 02:00 AM)
0 2 * * * /bin/bash /var/www/biolink/public_html/scripts/ops/backup_db.sh /var/backups/biolink > /dev/null 2>&1

cPanel Cron Job Setup

• Under Common Settings, choose Once Per Minute (* * * * *).
• In the Command field, enter:
  curl -s "https://yourdomain.com/api/cron/run?token=YOUR_CRON_SECRET" >/dev/null 2>&1
• Click Add New Cron Job.

8. SMTP & Email Configuration

Reliable transactional email delivery is required for user account verification, password resets, payment notifications, and contact forms.

1. Access Admin Settings

   Navigate to Super Admin → Settings → Email / SMTP.

2. Configure SMTP Parameters

   Field	Example Value	Notes
   SMTP Host	smtp.sendgrid.net / smtp.mailgun.org	Your SMTP provider server.
   SMTP Port	587 (or 465)	587 for TLS, 465 for SSL.
   Encryption	tls (or ssl)	Recommended: TLS.
   SMTP Username	apikey or email address	Supplied by your provider.
   SMTP Password	Your API key or password	Stored securely in database.
   From Email	[email protected]	Must match your verified sending domain.
   From Name	BioLink Pro	Display name in user inboxes.

3. Send Test Email

   Use the Send Test Email button to verify connection handshake and inbox delivery before saving.

9. Payment Gateways & Billing Configuration

BioLink Pro integrates multiple global and offline billing drivers out of the box with strict webhook signature verification, automated subscription lifecycle management, and idempotent transaction processing. Navigate to Super Admin → Settings → Payments to enable your preferred providers.

1. LemonSqueezy Configuration

LemonSqueezy acts as a Merchant of Record (MoR), handling global sales tax, VAT, and recurring SaaS billing.

1. API Key & Store Setup

   Generate an API Key from LemonSqueezy Dashboard → Settings → API Keys. Copy your Store ID from your store settings and paste both into Super Admin → Settings → Payments → LemonSqueezy.

2. Webhook Endpoint & Signing Secret

   In LemonSqueezy Dashboard → Settings → Webhooks, click Create Webhook and configure:

   • Callback URL: https://yourdomain.com/api/webhook/lemonsqueezy (or https://yourdomain.com/api/webhook?gateway=lemonsqueezy)
   • Signing Secret: Generate a high-entropy secret string and enter it in both LemonSqueezy and BioLink Pro settings. Every webhook payload is verified via HMAC-SHA256 signature check.
   • Events to Subscribe: Select the following lifecycle events to ensure automated provisioning, downgrades, and renewals:
     • subscription_created — Provisions subscriber upon initial purchase.
     • subscription_updated — Syncs renewals, plan upgrades, and billing period changes.
     • subscription_resumed & subscription_unpaused — Restores access when subscription restarts.
     • subscription_paused — Enforces past-due status upon payment pause.
     • subscription_cancelled — Marks cancellation while preserving access until current billing period end (grace period).
     • subscription_expired — Downgrades account to default Free tier immediately once grace period expires.
     • order_created — Automatically activates Lifetime (one-time purchase) tiers.
3. Variant IDs Mapping

   In your LemonSqueezy products, locate the numeric Variant ID for each pricing interval (Monthly, Annual, Lifetime). Then navigate to Super Admin → Plans → Edit Plan and input the corresponding IDs under LemonSqueezy Variant IDs.

4. Coupon Codes Synchronization (First-Payment Only)

   BioLink Pro coupons operate on a First Payment Only policy. When configuring a coupon in LemonSqueezy:

   • Create the discount code in LemonSqueezy Dashboard → Discounts using the exact same code created in BioLink Pro.
   • Set Duration to Once (First payment only) so recurring renewals bill at the regular plan rate.

2. Stripe Configuration

• Provide Publishable Key (pk_live_...) and Secret Key (sk_live_...).
• In Stripe Dashboard → Developers → Webhooks, create an endpoint pointing to:
  https://yourdomain.com/api/webhook/stripe
• Listen to events: checkout.session.completed, invoice.paid, customer.subscription.deleted, customer.subscription.updated.
• Copy your Signing Secret (whsec_...) into BioLink Pro settings.
• Coupons: BioLink Pro dynamically provisions one-time discount objects on Stripe (duration: once) ensuring subsequent renewals remain full price.

3. PayPal Configuration

• Enter your Client ID and Secret Key from PayPal Developer Portal.
• Set Mode to live (or sandbox for testing).
• Register Webhook URL: https://yourdomain.com/api/webhook/paypal and subscribe to PAYMENT.CAPTURE.COMPLETED and BILLING.SUBSCRIPTION.* events.
• Copy the Webhook ID into BioLink Pro settings to enable strict PayPal signature verification.

4. Bank Transfer / Manual Billing

• Toggle Bank Transfer to active in payment settings.
• Enter corporate account details, IBAN, BIC/SWIFT, and payment instructions.
• During checkout, customers can apply platform coupons and submit their bank receipt image / reference code.
• Administrators inspect, approve, or reject pending transfers directly from Super Admin → Billing → Offline Payments. Approval instantly applies the selected plan.

10. Coupon Codes & In-App Campaign Studio

BioLink Pro features a native coupon engine combined with an interactive Campaign Studio that displays high-converting modal promotions and upgrade banners to targeted user segments.

Synchronizing Coupons with Payment Gateways

Because BioLink Pro integrates with external payment processors, coupons must be coordinated across your gateway dashboards:

In-App Campaign Studio (Targeted Promotions)

Navigate to Super Admin → Finance → Coupons. When creating or editing any coupon, toggle In-App Campaign Promotion to enable marketing automation:

• Campaign Modal Display: Shows an interactive popup modal when targeted users browse their dashboard or profile builder.
• Audience Targeting:
  • All Users: Broad marketing promotions.
  • Free Tier Only: Encourages non-paying users to upgrade.
  • Specific User IDs: VIP discounts or retention offers for targeted accounts.
• Tenure Rules (Registration Days): Only show the offer to users registered for at least N days.
• Persistent Upgrade Banner: If enabled, users who dismiss the popup will still see a top reminder alert banner inside the /admin/upgrade checkout page while the campaign remains active.

11. Security & Anti-Bot Protection

Protect your platform from credential stuffing, spam account registration, and brute-force attacks by enabling modern captcha verification.

Cloudflare Turnstile (Recommended)

Turnstile delivers seamless privacy-focused verification without user friction:

1. Log into Cloudflare Dashboard → Turnstile and create a widget for your domain.
2. Select Managed (recommended).
3. Copy the Site Key and Secret Key into Super Admin → Settings → Security.
4. Enable Turnstile on Login, Registration, and Contact forms.

Rate Limiting Protection

The platform enforces intelligent rate limiting stored in api/cache/ratelimit/:

• login: 5 attempts / minute with progressive IP lockout.
• register: 3 attempts / minute.
• forgot_password: 3 attempts / minute.
• public_api: 120 requests / minute.

11. Custom Domains & CNAME Configuration

BioLink Pro enables users to connect custom personal domains to their biolink profiles.

DNS Setup for Users

Instruct users to configure their DNS records at their domain registrar:

• Subdomains (e.g. links.mybrand.com): Create a CNAME record pointing to yourdomain.com.
• Apex Domains (e.g. mybrand.com): Create an A record pointing to your server's public IPv4 address.

Server Configuration

Your web server (Apache or Nginx) must accept wildcards or catch-all server names so that incoming requests on custom hostnames reach BioLink Pro's router:

server {
    listen 80;
    listen 443 ssl http2;
    server_name yourdomain.com *.yourdomain.com;
    
    # SSL certificates (Wildcard Let's Encrypt recommended)
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    
    root /var/www/biolink/public_html;
    index index.php index.html;
    # ...
}

12. Apache Web Server (.htaccess)

BioLink Pro ships with an optimized .htaccess file pre-configured for Apache. Ensure mod_rewrite, mod_headers, and mod_deflate are active in your Apache configuration:

sudo a2enmod rewrite headers deflate expires
sudo systemctl restart apache2

Ensure your VirtualHost allows override directives:

<Directory /var/www/biolink/public_html>
    Options -Indexes +FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

13. Nginx Server Configuration

If deploying on an Nginx environment, use the following production-hardened virtual host configuration:

server {
    listen 80;
    listen [::]:80;
    server_name yourdomain.com www.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name yourdomain.com www.yourdomain.com;

    root /var/www/biolink/public_html;
    index index.php index.html;

    # SSL Certificates
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # Maximum client payload size
    client_max_body_size 64M;

    # Security Headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Block direct access to sensitive configuration and source files
    location ~ /\.(env|git|htaccess|sql|sqlite|log|bak)$ {
        deny all;
        return 404;
    }

    # Block script execution inside the user uploads directory
    location ~* ^/uploads/.*\.php$ {
        deny all;
        return 403;
    }

    # Static asset caching
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff2|woff|svg|webp|avif)$ {
        expires 30d;
        add_header Cache-Control "public, no-transform";
        try_files $uri =404;
    }

    # Primary Routing: send API and page requests to index.php
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # PHP-FPM execution
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_read_timeout 120;
    }
}

14. PHP Runtime Settings (php.ini)

Configure the following directives in your php.ini to ensure smooth handling of image uploads, themes, and background cron processing:

15. Updating the Platform

BioLink Pro features a streamlined update workflow using dedicated update archives (biolink_pro_update_vX.X.X.zip). The update process overwrites core application code while safeguarding your .env file, custom settings, and user uploaded files.

1. 1. Create Database & Config Backup

   Always create a fresh backup of your MySQL database and your .env file before applying an update.

2. 2. Upload Update Archive & Extract

   Upload biolink_pro_update_latest.zip to your server's root directory (public_html). Extract and confirm file overwrites when prompted. Update packages intentionally omit .env, /uploads, and /install to preserve your live data.

3. 3. Configure Update Token in .env

   Open your server's root .env file. Ensure UPDATE_SECRET is configured. If missing from an earlier version, add a random secret string or utilize your existing JWT_SECRET:

   .env — Update Secret Token Configuration Copy

   # Security Secrets
   JWT_SECRET=your_existing_jwt_secret_token
   UPDATE_SECRET=your_custom_secret_key_or_random_token

   Note: If UPDATE_SECRET is omitted from .env, the updater automatically accepts your existing JWT_SECRET value as the fallback token.

4. 4. Run Database Migrator (3 Supported Methods)

   Execute the automated schema synchronization using one of the following methods:

   Method A — Browser with Security Token (Recommended):

   Visit the updater URL in your browser with your secret token passed in the query string:

   URL — Direct Token Execution Copy

   https://yourdomain.com/update.php?token=your_custom_secret_key_or_random_token

   Method B — Active Super Admin Session:

   Log in as Super Admin in your browser first (e.g., at https://yourdomain.com/login), then in the same browser window open:

   https://yourdomain.com/update.php

   The updater detects your authenticated administrator session and executes the migration immediately.

   Method C — Server Terminal / CLI (Zero Downtime):

   If you have SSH terminal access, run the updater directly via PHP CLI without needing a browser:

   bash — CLI Execution Copy

   php update.php
   # Or run the core schema engine directly:
   php api/db_sync.php

   The schema engine will automatically inspect tables, add any missing columns, create new indexes, synchronize language translation keys, and refresh the system cache without interrupting active user sessions.

5. 5. Verify System Health & Cleanup

   Log in as Super Admin and check System Health (/admin/system-health) to confirm that database tables, cache, and storage paths report green.

   Optional Security Hardening: You can safely remove update.php from your server root once the migration is complete. If retained, it remains securely guarded by your UPDATE_SECRET.

16. Automated Backups & Disaster Recovery

The platform includes an automated CLI backup script located at scripts/ops/backup_db.sh:

# Run immediate backup
./scripts/ops/backup_db.sh /var/backups/biolink

# This creates a compressed, transaction-consistent SQL archive:
# biolink_pro_YYYYMMDD_HHMMSS.sql.gz and automatically prunes backups older than 14 days.

Restoring from Backup

gunzip < /var/backups/biolink/biolink_pro_YYYYMMDD_HHMMSS.sql.gz | mysql -u your_user -p your_database

17. Troubleshooting & FAQ