DS Diamonds - Premium Diamond Management & Sharing Platform

Version: 2.0
Last Updated: November 10, 2025

A modern, role-based diamond inventory and sharing system for manufacturers (admins), resellers (clients), and their end customers. Features secure invite links, read-only customer views, and full diamond management capabilities.

---

🌟 Features

Public Landing Page

• Modern, responsive design with gradient backgrounds
• Hero section with CTAs for client sign-in
• Featured diamond catalog preview
• Contact information and partner program details
• Mobile-responsive navigation with Alpine.js

Role-Based Access Control (RBAC)

Three distinct user roles:

1. Admin (Manufacturer) - Full system access

   • Manage all diamonds, staff, and masters
   • View all analytics and reports
   • Configure system settings
   • Access all client invites

2. Client (Reseller) - Limited business access

   • Browse available diamond inventory
   • Create secure invite links for customers
   • Manage own invites (view, revoke)
   • Track invite analytics (views, access count)

3. Customer (Read-Only) - Invite-based access

   • View diamonds shared via invite link
   • Read-only diamond specifications
   • Time-limited access (configurable expiry)
   • No login required (token-based)

Invite System

• Secure Token Generation: 64-character hex tokens using random_bytes()
• Time-Limited Access: Configurable expiry (1-90 days)
• Diamond Selection: Multi-select diamonds to share
• Customer Info: Optional name and contact tracking
• Revocation: Clients can revoke invites anytime
• Analytics: Track views, access count, last accessed time
• Rate Limiting: Configurable daily invite creation limits

Client Dashboard

• Modern card-based diamond grid
• Advanced filtering (search, shape, status)
• Detailed diamond modals with full specifications
• One-click invite creation from any diamond
• Responsive design with Tailwind CSS

Security Features

• Prepared SQL statements (PDO) for all queries
• Role-based page access control
• Token validation and expiry checks
• Rate limiting on invite creation
• Activity logging (admin actions)
• HTTPS recommended for production

---

📋 Prerequisites

• Web Server: Apache (WAMP, XAMPP, or LAMP)
• PHP: 7.4 or higher
• MySQL: 5.7 or higher (or MariaDB 10.3+)
• Composer: For dependency management (already included in /vendor)
• PHP Extensions: PDO, mysqli, mbstring, json

---

🚀 Installation

1. Clone or Download Repository

# Navigate to your web server directory
cd c:\wamp64\www

# Or for Linux/Mac
cd /var/www/html

# The project should be in ds_diamonds folder

2. Configure Database Connection

Edit config.php with your database credentials:

$servername = "localhost";
$username = "root";        // Your MySQL username
$password = "";            // Your MySQL password
$dbname = "ds_diamonds_db"; // Database name

3. Create Database

CREATE DATABASE IF NOT EXISTS ds_diamonds_db
CHARACTER SET utf8mb4
COLLATE utf8mb4_general_ci;

4. Run Initial Schema

Import the base SQL schema from SQL Commads to create all tables..txt:

# Via MySQL CLI
mysql -u root -p ds_diamonds_db < "SQL Commads to create all tables..txt"

# Or use phpMyAdmin:
# 1. Open phpMyAdmin
# 2. Select ds_diamonds_db database
# 3. Go to Import tab
# 4. Choose the SQL file and execute

5. Run Migrations

Import migrations.sql to add new role-based features:

mysql -u root -p ds_diamonds_db < migrations.sql

# Or via phpMyAdmin (same process as above)

This migration adds:

• role column to staff table (admin/client)
• client_id foreign key to customers table
• invites table for secure sharing
• invite_access_log table for analytics
• system_settings table for configuration
• Additional timestamp columns to existing tables

6. Verify Installation

1. Access the landing page: http://localhost/ds_diamonds/landing.php
2. Access login page: http://localhost/ds_diamonds/index.php
3. Default admin credentials (set in migration):
   • UserID: (check your staff table, usually ID 1)
   • Password: (your existing password)
   • Role: Will be set to 'admin' automatically for first user

---

🔐 Initial Setup

1. Set Admin Role

After running migrations, ensure your main account is set as admin:

UPDATE staff SET role = 'admin' WHERE id = 1;

2. Create Test Client

INSERT INTO staff (client_name, name, user_id, password, status, role)
VALUES ('Test Reseller Co', 'John Client', 'testclient', 'password123', 'Enable', 'client');

3. Configure System Settings

Login as admin and set these in the database (or create an admin UI later):

-- Update base URL for invite links
UPDATE system_settings
SET setting_value = 'http://localhost/ds_diamonds'
WHERE setting_key = 'app_base_url';

-- Update default invite expiry
UPDATE system_settings
SET setting_value = '7'
WHERE setting_key = 'invite_default_expiry_days';

-- Update rate limit
UPDATE system_settings
SET setting_value = '20'
WHERE setting_key = 'invite_max_per_client_daily';

---

📁 Project Structure

ds_diamonds/
├── landing.php                  # Public landing page (NEW)
├── index.php                    # Login page (UPDATED with role support)
├── config.php                   # Database configuration
├── auth_check.php               # RBAC helper functions (NEW)
│
├── Client Pages (NEW)
├── client_dashboard.php         # Client diamond browser
├── client_invite_create.php     # Create invite form
├── client_invites.php           # Manage invites
├── invite_view.php              # Public invite view (no auth)
│
├── Admin Pages (EXISTING)
├── home.php                     # Dashboard
├── diamond_master.php           # Diamond CRUD (UPDATED with customer view)
├── staff_master.php             # Staff management
├── customer_master.php          # Customer management
├── shared_links.php             # Legacy sharing system
├── config_generic.php           # System configuration
│
├── Master Pages (EXISTING)
├── shape_master.php
├── color_master.php
├── clarity_master.php
├── cut_master.php
├── polish_master.php
├── symmetry_master.php
│
├── Components (UPDATED)
├── header.php                   # Page header with auth check
├── sidebar.php                  # Navigation (UPDATED with role-based menus)
├── footer.php                   # Page footer
│
├── Database
├── migrations.sql               # New role-based schema (NEW)
├── SQL Commads to create all tables..txt  # Base schema
│
├── Assets
├── assets/images/shapes/        # Diamond shape SVGs
│
└── vendor/                      # Composer dependencies

---

🎯 User Flows

Admin (Manufacturer) Flow

1. Login with admin credentials → Redirected to home.php
2. Manage diamonds via diamond_master.php
3. Add/edit clients via staff_master.php (role = 'client')
4. View system configuration
5. Access all master data tables
6. View analytics and reports

Client (Reseller) Flow

1. Login with client credentials → Redirected to client_dashboard.php
2. Browse available diamonds (grid view with filters)
3. Click "Create Invite Link" on any diamond
4. Fill form: customer name, select diamonds, set expiry
5. Copy generated invite URL
6. Share URL with customer (email, SMS, WhatsApp, etc.)
7. Track invite analytics in client_invites.php
8. Revoke invite if needed

Customer (End User) Flow

1. Receive invite URL from reseller (e.g., http://domain.com/ds_diamonds/invite_view.php?token=abc123...)
2. Open URL in browser (no login required)
3. View shared diamonds in read-only mode
4. See full specifications, certifications
5. Contact reseller to purchase (in-person transaction)
6. URL expires after configured days

---

🔧 Configuration

Environment Variables / Settings

Edit system_settings table or create a UI to manage:

Setting Key	Default	Description
app_base_url	http://localhost/ds_diamonds	Base URL for generating invite links
invite_default_expiry_days	7	Default days before invite expires
invite_max_per_client_daily	20	Max invites a client can create per day
app_name	DS Diamonds	Application name
app_tagline	Exquisite diamonds, verified authenticity	Tagline

Customizing Invite Expiry

Clients can choose 1-90 days when creating invites. Default is set in settings.

Rate Limiting

Prevent abuse by limiting daily invite creation per client. Adjustable in system_settings.

---

🧪 Testing

Test Admin Login

URL: http://localhost/ds_diamonds/index.php
Role: Client (toggle)
UserID: (your admin user_id)
Password: (your password)

Test Client Login

URL: http://localhost/ds_diamonds/index.php
Role: Client (toggle)
UserID: testclient
Password: password123

Test Customer Login (Legacy)

URL: http://localhost/ds_diamonds/index.php
Role: Customer (toggle)
Customer Name: (from customers table)
Contact Number: (from customers table)

Test Invite Flow

1. Login as client
2. Navigate to "Create Invite"
3. Select 1-3 diamonds
4. Set expiry to 1 day
5. Submit and copy invite link
6. Open invite link in incognito window
7. Verify read-only diamond view
8. Wait 1 day and verify expiry message

Test Rate Limiting

1. Login as client
2. Create 20 invites in quick succession
3. Attempt 21st invite → should show error

---

🛡️ Security Best Practices

For Production Deployment

1. HTTPS Only

   • Use SSL certificate (Let's Encrypt recommended)
   • Update app_base_url to https:// in settings

2. Strong Passwords

   • Use password hashing (bcrypt/Argon2) instead of plaintext
   • Update login logic in index.php to use password_verify()

   Example:

   // When creating user
   $hashed = password_hash($password, PASSWORD_BCRYPT);
   
   // When logging in
   if (password_verify($input_password, $user['password'])) {
       // Login successful
   }

3. Database Security

   • Use non-root MySQL user
   • Grant only necessary permissions
   • Keep config.php outside web root if possible

4. Environment Variables

   • Move sensitive config to .env file
   • Use vlucas/phpdotenv package (already in vendor)
   • Add .env to .gitignore

5. Session Security

   • Add to config.php:

   ini_set('session.cookie_httponly', 1);
   ini_set('session.cookie_secure', 1); // If using HTTPS
   ini_set('session.use_strict_mode', 1);

6. SQL Injection Prevention

   • Already implemented: All queries use prepared statements
   • Never concatenate user input into SQL

7. XSS Prevention

   • Already implemented: All output uses htmlspecialchars() via h() helper
   • Continue using h() function for all user-generated content

8. Rate Limiting

   • Consider adding IP-based rate limiting for login attempts
   • Use libraries like symfony/rate-limiter

---

📊 Database Schema Overview

New Tables

invites

Primary table for invite system.

Column	Type	Description
id	INT	Primary key
client_id	INT	FK to staff table
token	VARCHAR(64)	Unique secure token
customer_name	VARCHAR(255)	Optional customer name
customer_contact	VARCHAR(100)	Optional contact info
note	TEXT	Private note for client
diamonds_shared	JSON	Array of diamond IDs
expires_at	DATETIME	Expiration timestamp
created_at	TIMESTAMP	Creation timestamp
used	TINYINT(1)	0=active, 1=revoked
access_count	INT	Number of times viewed
last_accessed_at	DATETIME	Last view timestamp

invite_access_log

Tracks each invite access for analytics.

Column	Type	Description
id	INT	Primary key
invite_id	INT	FK to invites
accessed_at	TIMESTAMP	Access time
ip_address	VARCHAR(45)	Visitor IP
user_agent	TEXT	Browser info

system_settings

Key-value store for configuration.

Column	Type	Description
id	INT	Primary key
setting_key	VARCHAR(100)	Unique key
setting_value	TEXT	Value
description	TEXT	Usage description
updated_at	TIMESTAMP	Last update

Modified Tables

staff (UPDATED)

Added role column for RBAC.

ALTER TABLE staff
ADD COLUMN role ENUM('admin', 'client') NOT NULL DEFAULT 'client';

customers (UPDATED)

Added client_id foreign key.

ALTER TABLE customers
ADD COLUMN client_id INT DEFAULT NULL,
ADD FOREIGN KEY (client_id) REFERENCES staff(id) ON DELETE CASCADE;

---

🎨 UI/UX Highlights

Design System

• Framework: Tailwind CSS (via CDN)
• Icons: Font Awesome 6.4.0
• Fonts: Inter (body), Playfair Display (headings)
• JS Library: Alpine.js 3.x (lightweight reactivity)

Color Palette

--primary: #7b2ff7 (purple)
--secondary: #f83077 (pink)
--dark: #0f172a (slate)
--gradient: linear-gradient(135deg, #7b2ff7, #f83077)

Components

• Cards: Rounded, shadow-md, hover effects
• Modals: Alpine.js powered, overlay with backdrop
• Forms: Rounded inputs with focus rings
• Buttons: Gradient backgrounds, hover animations
• Tables: Striped rows, hover states

Responsive Breakpoints

• Mobile: < 768px
• Tablet: 768px - 1024px
• Desktop: > 1024px

---

🔄 Migration from Legacy System

If you're upgrading from an older version:

1. Backup Database

mysqldump -u root -p ds_diamonds_db > backup_$(date +%Y%m%d).sql

2. Update Existing Staff Roles

-- Set your main account as admin
UPDATE staff SET role = 'admin' WHERE user_id = 'your_admin_userid';

-- Set all others as clients
UPDATE staff SET role = 'client' WHERE user_id != 'your_admin_userid';

3. Link Existing Customers to Clients

-- Example: Link all customers to a specific client
UPDATE customers SET client_id = 1 WHERE client_id IS NULL;

4. Test All Functionality

• Test admin login and navigation
• Test client login and dashboard
• Create a test invite and verify access
• Check legacy pages still work (diamond_master.php, etc.)

---

🐛 Troubleshooting

Issue: "Access denied" when logging in as client

Solution: Check if user has role = 'client' in staff table and status = 'Enable'.

SELECT id, name, user_id, role, status FROM staff WHERE user_id = 'your_userid';

Issue: Invite link shows "Invalid invite link"

Solution:

1. Check token format (should be 64 hex characters)
2. Verify invite exists in database
3. Check if invite is expired or revoked

SELECT * FROM invites WHERE token = 'your_token';

Issue: "Base URL" in invite links is wrong

Solution: Update system setting:

UPDATE system_settings
SET setting_value = 'https://yourdomain.com/ds_diamonds'
WHERE setting_key = 'app_base_url';

Issue: Client can't see "Create Invite" button

Solution: Ensure session has role = 'client'. Clear browser cache and re-login.

Issue: Diamond images not showing

Solution: Check that shape SVG files exist in assets/images/shapes/. If missing, add placeholder images or update to use Font Awesome icons only.

Issue: PHP errors about missing functions

Solution: Ensure auth_check.php is included at top of all protected pages:

require_once 'auth_check.php';

---

📈 Future Enhancements

Potential features for future development:

• Email notifications when invites are accessed
• QR code generation for invites
• Advanced analytics dashboard for clients
• Diamond comparison tool
• Wishlist/favorites for customers
• Multi-language support
• Dark mode toggle
• PDF export of diamond details
• WhatsApp/SMS integration for invite sharing
• Password reset via email
• Two-factor authentication (2FA)
• API endpoints for mobile app
• Real-time inventory sync
• Client branding (white-label invites)
• Advanced search with faceted filters

---

📞 Support

For issues or questions:

1. Check this README first
2. Review code comments in key files
3. Check browser console for JS errors
4. Check PHP error logs: c:\wamp64\logs\php_error.log
5. Verify database schema matches migrations

---

📄 License

© 2025 DS Diamonds. All rights reserved.

This is proprietary software. Unauthorized copying, distribution, or modification is prohibited.

---

🙏 Credits

Built with:

• PHP 7.4+
• MySQL 5.7+
• Tailwind CSS 3.x
• Alpine.js 3.x
• Font Awesome 6.4.0
• PhpSpreadsheet (for Excel operations)
• HTML Purifier (for security)

Developed by: DS Diamonds Development Team
Last Updated: November 10, 2025
Version: 2.0.0

---

✅ Quick Start Checklist

• Install WAMP/XAMPP and start Apache + MySQL
• Create ds_diamonds_db database
• Update config.php with database credentials
• Import SQL Commads to create all tables..txt
• Import migrations.sql
• Set first user as admin role
• Update app_base_url in system_settings
• Test admin login
• Create test client user
• Test client login
• Create test invite
• Open invite link and verify
• Configure HTTPS for production
• Implement password hashing
• Set up backups
• Deploy! 🚀

---

Happy Diamond Sharing! 💎