ww-filament

WittyWorkflow

Logo

Witty Workflow

A powerful platform for managing your business built with the TALL stack

🎮 Interactive Demo · 🐛 Report Bug · ✨ Request Feature

![Laravel](https://img.shields.io/badge/laravel-%23FF2D20.svg?style=for-the-badge&logo=laravel&logoColor=white) ![Livewire](https://img.shields.io/badge/livewire-%234e56a6.svg?style=for-the-badge&logo=livewire&logoColor=white) ![TailwindCSS](https://img.shields.io/badge/tailwindcss-%2338B2AC.svg?style=for-the-badge&logo=tailwind-css&logoColor=white) ![Filament](https://img.shields.io/badge/Filament-FFAA00?style=for-the-badge&logoColor=%23000000) ![Alpine.js](https://img.shields.io/badge/alpinejs-white.svg?style=for-the-badge&logo=alpinedotjs&logoColor=%238BC0D0) ![Stripe](https://img.shields.io/badge/Stripe-5469d4?style=for-the-badge&logo=stripe&logoColor=ffffff) ![Version](https://img.shields.io/badge/version-1.0.0-blue.svg) ![License](https://img.shields.io/badge/license-MIT-green.svg) ![PHP](https://img.shields.io/badge/PHP-8.1+-8892BF.svg)

⚠️ This app is in active development

⚠️ THIS REPOSITORY SHOULD BE USED ON A BRAND-NEW PROJECT

📋 Table of Contents
  1. About The Project
  2. Getting Started
  3. Command list
  4. Configuration
  5. Shop
  6. Appointment Management
  7. Testing
  8. Customization Guide
  9. Deployment
  10. Security
  11. Performance Optimization
  12. Usage
  13. Roadmap
  14. Contributing
  15. License
  16. Contact
  17. Acknowledgments
  18. Known issues

🚀 About The Project

WittyWorkflow is a TALL stack (Tailwind CSS, Alpine.js, Laravel, Livewire) foundation designed for building niche marketplaces and small business management tools. Whether you’re crafting an e-commerce shop, managing appointments, or creating custom workflows, this modular platform—powered by Filament PHP—offers a robust starting point. It’s built to be forked, extended, and deployed fast, with features like role-based dashboards, Stripe payments, and customizable UI out of the box.

Originally a demo app, WittyWorkflow has evolved into a versatile base for real-world projects. A prime example? It’s being adapted into the Artisanal Food Production Manager—a marketplace example connecting artisanal producers to customers, complete with product listings, orders, and secure payments. Developers can use it as-is for small business needs or tailor it to specialized industries like handmade goods, local services, or boutique retail.

🎮 Interactive Demo

Watch a guided tour of Witty Workflow’s key features and intuitive interface.

Interactive Demo

✨ Key Features

(back to top)

🛠️ Built With

This section lists all major frameworks/libraries used to bootstrap this project.

Laravel Livewire TailwindCSS Filament Alpine.js Stripe

(back to top)

💼 Use Cases

WittyWorkflow powers niche apps—here’s how:

Fork it, tweak it—build your vision fast.

🚀 Getting Started

Get WittyWorkflow running in minutes—perfect for prototyping or building your next niche app.

📋 Prerequisites

Before you begin, ensure your development environment meets these requirements:

⚡ Quickstart

  1. Clone the repo: 
    git clone https://github.com/kristi11/ww-filament.git
  2. Cd into project 
     cd ww-filament
  3. Install NPM dependencies 
     npm install
  4. Install the composer dependencies. 
    composer install
  5. Create a copy of your .env file. 
     cp .env.example .env
  6. Generate an app encryption key. 
    php artisan key:generate

    Note: If using Laravel Forge, there’s no need to generate a key since Forge handles key generation when creating the server.

  7. Create an empty database for your application. We recommend using TablePlus, but you can use any database management tool you prefer.

  8. In the .env file, add database information to allow Laravel to connect to the database. The default database name is ww_filament. If you are using a different name, you’ll need to edit the DB_DATABASE variable in the .env file with your database name.

  9. Migrate and seed the database. 
    php artisan migrate:fresh --seed
  10. WittyWorkflow uses Shield plugin to provide proper user roles. We need to set up the plugin and generate the permissions for that package: 
       php artisan shield:setup --fresh
   php artisan shield:generate --all --panel=admin

Then define the super admin of the system:

   php artisan shield:super-admin --user="1"

--user=1 is the id of the user that will be the super admin. You can change it to whatever user you want to be the super admin.

  1. Link the storage folder. 
    php artisan storage:link
  2. Run the application. 
    php artisan serve
  3. Visit your application in the browser. 
    http://localhost:8000
  4. Compile assets for development: 
    npm run dev

📝 Command list

For quick reference, here’s the complete list of commands to set up WittyWorkflow:

git clone https://github.com/kristi11/ww-filament.git .
npm install
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate:fresh --seed
php artisan shield:setup --fresh
php artisan shield:generate --all --panel=admin
php artisan shield:super-admin --user="1"
php artisan storage:link
npm run dev
php artisan serve

❓ Troubleshooting

If you encounter issues during installation, here are solutions to common problems:

Issue Solution
Class not found errors Run composer dump-autoload
Node.js errors Ensure you’re using Node.js 16+ with node -v
Database connection errors Verify credentials in .env file
Permission issues Check directory permissions, especially for storage and bootstrap/cache
Blank page after installation Check PHP error logs and ensure all requirements are met
Missing images/assets Run php artisan storage:link again
Shield errors Run php artisan optimize:clear then retry Shield commands

For more complex issues, check the Laravel documentation or open an issue on our GitHub repository.

📧 Email Configuration

[!NOTE] Don’t forget to update your Mail settings to reflect your production server’s needs

For local email testing, we recommend Mailtrap. To use Mailtrap:

  1. Create a Mailtrap account
  2. Add your Mailtrap credentials to the .env file:
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your_email
MAIL_FROM_NAME="${APP_NAME}"

If you are using Laravel Forge, you can add the credentials to the server environment variables.

🛒 Shop

WittyWorkflow includes a fully-featured e-commerce system built with the TALL stack and integrated with Stripe for payment processing. This section will guide you through setting up and using the shop functionality.

🏗️ Shop Architecture Overview

The shop system consists of several key components:

⚙️ Setting Up the Shop

1. Stripe Integration

First, add your Stripe credentials to your .env file:

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret
STRIPE_WEBHOOK_SECRET=your-stripe-webhook-secret
Development Environment Setup

For local testing:

  1. Install stripe-cli
  2. Run stripe login to authenticate with your Stripe account
  3. Start the webhook listener: 
    stripe listen --forward-to {your-local-url}/stripe/webhook --format JSON
  4. Copy the webhook signing secret provided by the CLI to your .env file as STRIPE_WEBHOOK_SECRET
Production Environment Setup

For production:

  1. Run php artisan cashier:webhook on your server to register the webhook with Stripe
  2. Go to the Stripe Webhooks Dashboard
  3. Click on the newly created webhook
  4. Copy the “Signing Secret” to your .env file as STRIPE_WEBHOOK_SECRET
  5. Ensure the checkout.session.completed event is enabled:
    • Click the “…” button on the webhook
    • Choose “Update details”
    • Under “Events to send”, click “Select events…”
    • Add checkout.session.completed

2. Database Configuration

The shop system uses several database tables:

These tables are created automatically when you run migrations.

🛍️ Using the Shop System

Product Management

Products are managed through the Filament admin panel:

  1. Navigate to the Products section in the admin panel
  2. Create products with basic information (name, description, price, image)
  3. Add variants for each product (size, color, etc.)

Cart Functionality

The cart system allows users to:

The cart is implemented using the Cart and CartItems models, with the AddProductVariantToCart action handling the addition of products.

Checkout Process

The checkout process is handled by:

  1. CreateStripeCheckoutSession: Creates a Stripe checkout session from the cart
  2. HandleCheckoutSessionCompleted: Processes the completed checkout, creates an order, and clears the cart

Order Management

After checkout, orders are:

  1. Created in the database with billing and shipping information
  2. Associated with the user who made the purchase
  3. Viewable in the admin panel for management

🧪 Testing the Shop

To test purchases in your development environment:

  1. Use Stripe’s test card number: 4242 4242 4242 4242
  2. Any future expiration date (e.g., 03/30)
  3. Any 3-digit CVC code (e.g., 123)
  4. Any name and address information

🚀 Going Live

To switch to production mode:

  1. Complete your business profile in the Stripe Dashboard
  2. Switch from test to live API keys in your .env file
  3. Ensure your webhook is properly configured for the live environment
  4. Test the complete purchase flow with a real card (consider using a small amount)

🔧 Customizing the Shop

The shop system is designed to be customizable:

See the Adding Variants section for detailed instructions on customizing product variants.

(back to top)

⚙️ Configuration

Disabled features:

[!IMPORTANT]

Switch the canEdit() function in CRUDSettingsResource.php to true ose false to enable or disable choosing whether the admin should be able to edit content or not.

Side note:

If the canCreate(), canEdit() or canDelete() functions return anything other than a true or false value is best not to mess with that value because that value is supposed to be that way.

WittyWorkflow uses filament-breezy to manage user profiles. Change the following value to shouldRegisterUserMenu: true/false depending on your app’s needs, to enable/disable profile editing on AdminPanelProvider.php and TeamPanelProvider.php for the Admin and Team member roles

->myProfile(
    shouldRegisterUserMenu: false, // Sets the 'account' link in the panel User Menu (default = false)
    shouldRegisterNavigation: false, // Adds a main navigation item for the My Profile page (default = false)
    navigationGroup: 'Settings', // Sets the navigation group for the My Profile page (default = null)
    hasAvatars: false, // Enables the avatar upload form component (default = false)
    slug: 'profile' // Sets the slug for the profile page (default = 'my-profile')

)
->enableTwoFactorAuthentication(
    force: false, // force the user to enable 2FA before they can use the application (default = false)
)

👥 Role configuration

WittyWorkflow used the Shield package to manage roles as stated above. In order to give permissions to manage appointments go on the Roles section of the dashboard, inside the Settings sidebar menu group and for both team_user and panel_user choose select all on the Appointment model permissions and to give the panel_user view permissions on the gallery choose view and view any under the Gallery model permissions. Also give the panel_user all permissions on the Order model permissions.

🔑 Role explanation

In order to use the Team role you need to create the role from the admin panel and the name of the role should be ‘team_user’ as it doesn’t exist by default and then assign that role to a desired user. Multiple roles can be assigned to a user

🔄 Panel switching

[!NOTE]

In order to properly switch user panels for different roles the admin of the system must be assigned all the available roles (super_admin, team_user and panel_user) in the user resource. That way the admin will not be prompted with a 403 code when trying to access a panel that he doesn’t have access to.

🔄 Adding variants

There are quite a few steps you need to take to add/edit/delete variants, and I’ll walk you through all of them:

If the above steps have been implemented, your newly created variant is ready for use throughout the app.

[!NOTE]

The App comes preloaded with some general variants and some tech variants. You should add the variant types that fit the type of store you’re building.

[!Important]

OTP is now available for an extra added layer of security. To enable OTP just go to your desired panels and uncomment //FilamentOtpLoginPlugin::make(),. The available panels are AdminPanelProvider.php, CustomerPanelProvider.php and TeamPanelProvider.php. If you’re going to enable OTP is advisable to enable it on all panels but that depends on your app’s needs.

(back to top)

📅 Appointment Management

WittyWorkflow includes a comprehensive appointment scheduling system that integrates with email notifications and calendar systems.

🏗️ Appointment System Architecture

The appointment system consists of several key components:

⚙️ Setting Up Appointments

  1. Configure Business Hours:
    • Navigate to the Business Hours section in the admin panel
    • Set your regular operating hours for each day of the week
    • Configure special hours for holidays or events
  2. Set Up Services:
    • Create services that can be booked through the Services section
    • Define duration, price, and description for each service
    • Assign services to specific team members if needed
  3. Configure Email Templates:
    • Customize email templates for appointment confirmations and reminders
    • Set up notification preferences for both staff and customers

📋 Managing Appointments

Appointments can be managed through the Filament admin panel:

  1. View Appointments:
    • See all upcoming appointments in a calendar or list view
    • Filter by date, service, or status
  2. Create Appointments:
    • Add appointments manually for walk-in customers
  3. Update Appointments:
    • Reschedule appointments as needed
    • Change service or duration
    • Add notes or special requirements
  4. Cancel Appointments:
    • Cancel with automatic notification to the customer
    • Optionally offer rebooking options

🔧 Customizing the Appointment System

The appointment system can be customized in several ways:

🧪 Testing

WittyWorkflow comes with a comprehensive test suite covering models, features, and integrations.

🏃‍♂️ Running Tests

# Run all tests
php artisan test

# Run specific test suite
php artisan test --testsuite=Feature

# Run specific test
php artisan test --filter=HeroTest

📁 Test Structure

The test files are organized in the following directories:

✍️ Writing New Tests

When adding new features, create corresponding tests in the appropriate directory:

Example of a basic model test:

/** @test */
public function it_can_create_a_model()
{
    $model = YourModel::factory()->create();
    $this->assertInstanceOf(YourModel::class, $model);
    $this->assertDatabaseHas('your_models', ['id' => $model->id]);
}

🎨 Customization Guide

WittyWorkflow is designed to be highly customizable without modifying core files.

🎭 Theme Customization

🧩 Extending Core Functionality

📚 Common Customization Examples

  1. Adding a Blog:
    • Create a Blog model and migration
    • Add a Filament resource for managing blog posts
    • Create public routes and views for displaying posts
  2. Custom User Roles:
    • Extend the Shield configuration to add new roles
    • Define permissions for the new roles
    • Create role-specific dashboards or views
  3. Payment Gateway Integration:
    • Add alternative payment methods beyond Stripe
    • Create payment gateway service classes
    • Integrate with checkout process

🚀 Deployment

🖥️ Server Requirements

📋 Deployment Steps

  1. Set up your web server and database:
    • Configure Nginx/Apache with proper PHP settings
    • Create a database for your application
  2. Clone the repository to your server: 
    git clone https://github.com/kristi11/ww-filament.git /path/to/your/site
  3. Install dependencies: 
    composer install --no-dev --optimize-autoloader
npm install && npm run build
  4. Set up environment variables:
    • Copy .env.example to .env
    • Configure database, mail, and other settings
    • Generate application key: php artisan key:generate
  5. Run migrations: 
    php artisan migrate
  6. Set up task scheduling: Add this to your crontab: ```
            • cd /path-to-your-project && php artisan schedule:run » /dev/null 2>&1 ```
  7. Configure caching: 
    php artisan config:cache
php artisan route:cache
php artisan view:cache

🌐 Platform-Specific Guides

🔒 Security

WittyWorkflow implements multiple security features to protect your application and data.

🔐 Authentication Options

🛡️ Authorization System

🔒 Security Best Practices

🔏 Data Protection

⚡ Performance Optimization

📦 Caching Strategies

🗄️ Database Optimization

🚀 Asset Optimization

📊 Monitoring and Profiling

🔍 Usage

To access the `super-admin dashboard, go to the Super-admin dashboard and enter the following credentials::

Email: admin@example.com
Password: password

To access the team dashboard go to the Team dashboard and enter the following credentials:

Email: team@example.com
Password: password

To access the customer dashboard go to the Customer dashboard and create an account

(back to top)

🗺️ Roadmap

  1. Create separate dashboards for each user role
  2. Add Filament Shield for managing user roles and permissions
  3. Create business information resources (appointments, services, users etc. )
  4. Add socials resource for referencing business’s social profiles
  5. Add CRUD functionality to sections of the public page for a more controlled and customizable experience
  6. Add Hero animations
  7. Add footer resources to give users an easy way to add their policies, FAQ and other business related information
  8. Add flash notifications and email notifications for appointment changes
  9. Add shop for purchases
  10. Improve visuals (ongoing effort)
  11. Add Announce package to announce different messages to system users
  12. Add Themes package to give users more options on system layout and design
  13. Add Filament Breezy for 2-factor authentication and better profile updating
  14. Add Language-switch to support different languages
  15. Add Spatie Laravel Health to check how the app is running.
  16. Add One Time Passwords (OTP) for an extra added layer of security
  17. Add Panel switch so the administrator switches between the panels for each of the available roles to see what’s available for that particular panel and make the necessary changes if needed
  18. Add auto logout plugin where you can set an auto logout timer to bump up security

🔮 Whats-next

WittyWorkflow is evolving—here’s what’s next:

(back to top)

[!NOTE]

Known issues

The following are the known issues that need addressing and I hope that the community will step in and work on them:

(back to top)

🔧 Workaround

(back to top)

🤝 Contributing

Love open source? Help shape WittyWorkflow:

🔄 Development Workflow

  1. Fork the repository:
    • Click the “Fork” button at the top right of the repository page
    • Clone your fork locally: git clone https://github.com/YOUR-USERNAME/ww-filament.git
  2. Create a feature branch: 
    git checkout -b feature/your-idea
  3. Implement your changes:
    • Follow the coding standards (PSR-12)
    • Write or update tests for your changes
    • Ensure all tests pass: php artisan test
  4. Commit your changes: 
    git commit -m "Add cool thing"

    Use descriptive commit messages that explain what changes were made and why.

  5. Push to your fork: 
    git push origin feature/your-idea
  6. Submit a pull request:
    • Go to the original repository
    • Click “New pull request”
    • Select “compare across forks”
    • Select your fork and branch
    • Fill out the PR template with details about your changes

📝 Code Style Guidelines

📤 Pull Request Process

  1. Update the README.md with details of changes if applicable
  2. Update the CHANGELOG.md with details of changes
  3. The PR will be merged once reviewed and approved

Check Issues for tasks (e.g., cart bug)—email tanellari@gmail.com with questions.

(back to top)

📄 License

This project is distributed under the MIT License, one of the most permissive and widely used open source licenses.

📋 What this means for developers:

📜 MIT License Summary

Copyright (c) 2024 Kristi Tanellari

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

📚 Useful Resources

(back to top)

📞 Contact

Connect with Me

GitHub Email

Project Link: https://github.com/kristi11/ww-filament/

(back to top)

🙏 Acknowledgments

I’ve included a few of my favorite links to kick things off!

(back to top)