A powerful, production-ready, multi-tenant Business Process Automation (BPM) SaaS platform built with PHP and MySQL. SplashWorkflows enables organizations to build custom workflows, automate business processes, manage approvals, and track workflow instances similar to platforms like Pipefy and Kissflow.

• Multi-Tenant Architecture: Secure tenant isolation with shared database
• Custom Workflow Builder: Create workflows with stages, transitions, and permissions
• Dynamic Form Builder: Build custom forms with various field types for each workflow
• Workflow Instances: Run workflow instances through stages with full tracking
• Approvals & Tasks: Manage approvals and task assignments
• Activity Logs: Complete audit trail of all actions
• Role-Based Access Control: Six user roles with granular permissions
• SLA Management: Track and monitor SLA compliance
• Notifications: In-app and email notifications (simulated)
• REST API: Full-featured REST API for integrations
• Reports: Comprehensive reporting with CSV export
• Dashboard: Real-time KPIs and metrics
• File Attachments: Secure file upload and management

• Flexible Plans: Free trial, Starter, Professional, and Enterprise plans
• Quota Enforcement: Automatic enforcement of plan limits
• Usage Tracking: Monitor users, workflows, instances, storage, and API calls
• Billing Management: Invoice and payment tracking (simulated gateway)

• Password Hashing: bcrypt password hashing
• CSRF Protection: Built-in CSRF protection for all forms
• SQL Injection Prevention: Prepared statements throughout
• Tenant Isolation: Strict tenant_id filtering in all queries
• Login Protection: Brute-force protection with account locking
• Input Validation: Comprehensive validation and sanitization
• Secure File Uploads: MIME type validation and secure storage

• PHP: 7.0+ (compatible with PHP 7.x - 8.x)
• MySQL: 5.7+ / MariaDB 10.2+
• Architecture: Custom lightweight MVC
• Frontend: HTML5, CSS3, Vanilla JavaScript
• No Frameworks: Pure PHP implementation

• PHP 7.0 or higher
• MySQL 5.7+ or MariaDB 10.2+
• Apache or Nginx web server
• PHP Extensions:
  • pdo_mysql
  • mbstring
  • openssl
  • json
  • fileinfo

git clone https://github.com/ahmedsaadawi13/SplashWorkflows.git
cd SplashWorkflows

cp .env.example .env

Edit .env and configure your settings:

DB_HOST=localhost
DB_PORT=3306
DB_NAME=splashworkflows
DB_USER=root
DB_PASS=your_password

APP_URL=http://localhost
APP_ENV=production
APP_DEBUG=false
SESSION_SECRET=your_random_secret_key_here

mysql -u root -p

CREATE DATABASE splashworkflows CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
exit;

mysql -u root -p splashworkflows < database.sql

chmod -R 755 storage/
chmod -R 755 storage/uploads/
chmod -R 755 storage/logs/

Create a virtual host configuration:

<VirtualHost *:80>
    ServerName splashworkflows.local
    DocumentRoot /path/to/SplashWorkflows/public

    <Directory /path/to/SplashWorkflows/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/splashworkflows-error.log
    CustomLog ${APACHE_LOG_DIR}/splashworkflows-access.log combined
</VirtualHost>

Enable mod_rewrite:

sudo a2enmod rewrite
sudo systemctl restart apache2

server {
    listen 80;
    server_name splashworkflows.local;
    root /path/to/SplashWorkflows/public;

    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}

Open your browser and navigate to:

http://splashworkflows.local

Default Platform Admin Credentials:

• Email: admin@splashworkflows.com
• Password: admin123

Change this password immediately after first login!

SplashWorkflows supports six user roles:

1. platform_admin: SaaS platform owner - manages tenants and global settings
2. tenant_admin: Company administrator - manages users, workflows, and settings
3. process_owner: Workflow creator - creates and manages workflows
4. approver: Approves workflow steps and tasks
5. collaborator: Works on tasks and fills forms
6. viewer: Read-only access

All API requests require an API key in the header:

X-API-KEY: sk_your_api_key_here

To generate an API key:

1. Log in as tenant_admin
2. Go to Settings → API Keys
3. Click "Generate New API Key"

Endpoint: POST /api/workflows/{workflow_key}/instances/create

Request Body:

{
  "title": "New Purchase Request",
  "fields": {
    "amount": "2500",
    "department": "IT",
    "description": "Laptops for new employees"
  },
  "priority": "high"
}

Response:

{
  "status": "success",
  "instance_id": 123,
  "instance_number": "WF-PR-00123",
  "current_stage": "Requested"
}

Endpoint: POST /api/instances/{instance_id}/transition

Request Body:

{
  "to_stage_key": "approved",
  "comment": "Approved by manager"
}

Response:

{
  "status": "success",
  "new_stage": "Approved",
  "instance_status": "in_progress"
}

Endpoint: GET /api/instances/{instance_id}

Response:

{
  "status": "success",
  "instance": {
    "id": 123,
    "number": "WF-PR-00123",
    "title": "New Purchase Request",
    "workflow_name": "Purchase Requests",
    "current_stage": "Approved",
    "status": "in_progress",
    "priority": "high",
    "created_by": "John Doe",
    "assigned_to": "Jane Smith",
    "created_at": "2025-01-15 10:30:00",
    "fields": {
      "amount": "2500",
      "department": "IT",
      "description": "Laptops for new employees"
    }
  }
}

Endpoint: GET /api/workflows/{workflow_key}/instances

Query Parameters:

• status (optional): Filter by status (open, in_progress, completed)
• stage_key (optional): Filter by stage key
• page (optional): Page number
• per_page (optional): Items per page (default: 20)

Response:

{
  "status": "success",
  "total": 45,
  "instances": [
    {
      "id": 123,
      "number": "WF-PR-00123",
      "title": "New Purchase Request",
      "workflow_name": "Purchase Requests",
      "current_stage": "Approved",
      "status": "in_progress",
      "priority": "high",
      "created_at": "2025-01-15 10:30:00"
    }
  ]
}

All errors return a consistent format:

{
  "status": "error",
  "message": "Error description",
  "code": "ERROR_CODE"
}

Common Error Codes:

• MISSING_API_KEY: API key not provided
• INVALID_API_KEY: API key is invalid or inactive
• WORKFLOW_NOT_FOUND: Workflow does not exist
• INSTANCE_NOT_FOUND: Instance does not exist
• VALIDATION_ERROR: Request validation failed
• METHOD_NOT_ALLOWED: HTTP method not allowed
• SERVER_ERROR: Internal server error

SplashWorkflows includes four pre-configured plans:

SplashWorkflows/
├── app/
│   ├── controllers/      # Application controllers
│   ├── models/          # Database models
│   ├── views/           # View templates
│   ├── core/            # Core MVC classes
│   └── helpers/         # Helper classes
├── config/              # Configuration files
├── public/              # Public web root
│   ├── assets/          # CSS, JS, images
│   └── index.php        # Application entry point
├── storage/
│   ├── uploads/         # User uploads
│   └── logs/            # Application logs
├── database.sql         # Database schema
├── .env.example         # Environment template
└── README.md           # This file

For automated tasks, set up these cron jobs:

# Check SLA breaches every hour
0 * * * * php /path/to/SplashWorkflows/cron/check-sla.php

# Process email notifications queue every 5 minutes
*/5 * * * * php /path/to/SplashWorkflows/cron/send-emails.php

# Update usage statistics daily
0 0 * * * php /path/to/SplashWorkflows/cron/update-usage.php

Set in .env:

APP_ENV=development
APP_DEBUG=true

All database changes are tracked in database.sql. To update:

mysql -u root -p splashworkflows < database.sql

• User registration creates tenant and admin user
• Login with valid credentials works
• Login with invalid credentials fails
• Account locks after 5 failed attempts
• Platform admin can access all tenants
• Tenant admin can only access their tenant
• Role-based access control enforced

• Create workflow with stages
• Add form fields to workflow
• Define stage transitions
• Set workflow permissions

• Create instance with form data
• Instance number auto-generated correctly
• Transition instance through stages
• Add comments to instance
• Upload attachments to instance
• View complete instance history

• API authentication with valid key works
• API authentication with invalid key fails
• Create instance via API
• Transition instance via API
• Get instance details via API
• List instances via API with filters

• New tenant gets free trial plan
• Quota limits enforced (users, workflows, instances)
• Usage tracked correctly
• Subscription status affects access

• CSRF protection prevents unauthorized requests
• SQL injection prevented by prepared statements
• Tenant isolation enforced in all queries
• XSS prevented by output escaping
• File upload validates MIME types

1. Change default passwords
2. Set strong SESSION_SECRET
3. Disable APP_DEBUG in production
4. Use HTTPS (SSL certificate)
5. Configure firewall rules
6. Regular database backups
7. Keep PHP and MySQL updated
8. Monitor logs regularly

1. Enable PHP OPcache
2. Add database indexes (already included in schema)
3. Use CDN for static assets
4. Enable Gzip compression
5. Configure PHP-FPM properly
6. Use Redis for sessions (optional)

# Daily database backup
mysqldump -u root -p splashworkflows > backup_$(date +%Y%m%d).sql

# Backup uploaded files
tar -czf uploads_$(date +%Y%m%d).tar.gz storage/uploads/

For issues, questions, or contributions, please open an issue or pull request on GitHub.

This project is open-source software. Check the LICENSE file for details.

Built with ❤️ for the open-source community.

SplashWorkflows - Streamline Your Business Processes