
A powerful platform for managing your business built with the TALL stack
๐ฎ Interactive Demo
ยท
๐ Report Bug
ยท
โจ Request Feature
โ ๏ธ This app is in active development
โ ๏ธ THIS REPOSITORY SHOULD BE USED ON A BRAND-NEW PROJECT
๐ Table of Contents
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.
Watch a guided tour of Witty Workflow's key features and intuitive interface.

-
๐ Dynamic Hero: Capture attention with a visually stunning, admin-customizable hero sectionโfully editable via Filament for a seamless experience.
-
๐ Role-Based Access: Leverage Filament PHP for flexible, role-based dashboardsโadmins control all, team members and customers (e.g., producers/retailers) get tailored views, powered by Shield.
-
โก SPA-Like Navigation: Enjoy smooth transitions with Livewire's
wire:navigate
โenhances UX across panels and public pages. -
๐ Customizable Contact & Footer: Boost engagement with a public email form and admin-editable footer for terms, help, or business details.
-
๐ E-commerce Module: A TALL stack shop with Stripe integration, product management, and admin controlโperfect for niches like artisanal food.
-
๐ Appointment Management: Schedule and manage appointments with email notificationsโoptional for service-based apps.
-
๐ Security Suite: Protect accounts with 2-Factor Authentication (2FA) and One-Time Passwords (OTP)โtoggleable for your needs.
-
๐จ Theme Customization: Tailor the app's look with admin-controlled themes and section visibilityโswap styles without code.
-
๐ Section Positioning: Control the order of public page sections through an intuitive admin interfaceโcustomize the user experience without touching code.
-
๐ Application Health: Monitor performance and server status with Spatie Laravel Healthโactionable insights from the dashboard.
-
โ๏ธ Business Settings: Manage announcements, visibility, and niche-specific dataโadaptable for any small business or marketplace.
-
๐งฐ Developer Tools: Demo seeds, and modular structureโfork and extend with ease.
This section lists all major frameworks/libraries used to bootstrap this project.
- Laravel 10.x
- Filament 3.x
- PHP 8.1
- Artisanal Food Marketplace: Producers list products, customers order, payments via Stripe.
- Local Service Hub: Book appointments for craftspeople, manage team schedules, customize the public page.
- Boutique E-commerce: Run a standalone shop with themed UI, secure logins, and order insights.
- Creative Freelancer Platform: Artists and designers showcase portfolios, clients request quotes.
- Pop-up Event Manager: Coordinate vendors, sell tickets.
- Fitness Studio Management: Schedule classes.
Fork it, tweak itโbuild your vision fast.
Get WittyWorkflow running in minutesโperfect for prototyping or building your next niche app.
Before you begin, ensure your development environment meets these requirements:
- PHP 8.1+ with the following extensions:
- BCMath
- Ctype
- Fileinfo
- JSON
- Mbstring
- OpenSSL
- PDO
- Tokenizer
- XML
- Composer 2.0+
- Node.js 16+ and NPM
- MySQL 5.7+ or PostgreSQL 10+
- Git
-
Clone the repo:
git clone https://github.com/kristi11/ww-filament.git
-
Cd into project
cd ww-filament
-
Install NPM dependencies
npm install
-
Install the composer dependencies.
composer install
-
Create a copy of your .env file.
cp .env.example .env
-
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.
-
Create an empty database for your application. We recommend using TablePlus, but you can use any database management tool you prefer.
-
In the
.env
file, add database information to allow Laravel to connect to the database. The default database name isww_filament
. If you are using a different name, you'll need to edit theDB_DATABASE
variable in the.env
file with your database name. -
Migrate and seed the database.
php artisan migrate:fresh --seed
-
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
.
-
Link the storage folder.
php artisan storage:link
-
Run the application.
php artisan serve
-
Visit your application in the browser.
http://localhost:8000
-
Compile assets for development:
npm run dev
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
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.
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:
- Create a Mailtrap account
- 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.
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.
The shop system consists of several key components:
- Products & Variants: Products can have multiple variants (size, color, etc.)
- Cart System: Manages items added to a user's cart
- Checkout Process: Integrated with Stripe for secure payments
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
For local testing:
- Install stripe-cli
- Run
stripe login
to authenticate with your Stripe account - Start the webhook listener:
stripe listen --forward-to {your-local-url}/stripe/webhook --format JSON
- Copy the webhook signing secret provided by the CLI to your
.env
file asSTRIPE_WEBHOOK_SECRET
For production:
- Run
php artisan cashier:webhook
on your server to register the webhook with Stripe - Go to the Stripe Webhooks Dashboard
- Click on the newly created webhook
- Copy the "Signing Secret" to your
.env
file asSTRIPE_WEBHOOK_SECRET
- 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
The shop system uses several database tables:
products
: Stores product informationproduct_variants
: Stores variant information for productscarts
: Manages user shopping cartscart_items
: Stores items in cartsorders
: Tracks completed ordersorder_items
: Stores items in orders
These tables are created automatically when you run migrations.
Products are managed through the Filament admin panel:
- Navigate to the Products section in the admin panel
- Create products with basic information (name, description, price, image)
- Add variants for each product (size, color, etc.)
The cart system allows users to:
- Add products to their cart
- Update quantities
- Remove items
- View cart totals
The cart is implemented using the Cart
and CartItems
models, with the AddProductVariantToCart
action handling the addition of products.
The checkout process is handled by:
CreateStripeCheckoutSession
: Creates a Stripe checkout session from the cartHandleCheckoutSessionCompleted
: Processes the completed checkout, creates an order, and clears the cart
After checkout, orders are:
- Created in the database with billing and shipping information
- Associated with the user who made the purchase
- Viewable in the admin panel for management
To test purchases in your development environment:
- Use Stripe's test card number:
4242 4242 4242 4242
- Any future expiration date (e.g.,
03/30
) - Any 3-digit CVC code (e.g.,
123
) - Any name and address information
To switch to production mode:
- Complete your business profile in the Stripe Dashboard
- Switch from test to live API keys in your
.env
file - Ensure your webhook is properly configured for the live environment
- Test the complete purchase flow with a real card (consider using a small amount)
The shop system is designed to be customizable:
- Product Variants: Add custom variants in
app/Enums/
and update theProductVariant
model - Checkout Flow: Modify the
CreateStripeCheckoutSession
class to customize checkout options - Order Processing: Extend the
HandleCheckoutSessionCompleted
class to add custom logic after purchase
See the Adding Variants section for detailed instructions on customizing product variants.
Important
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)
)
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.
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
super_admin
= The super admin of the systemteam_user
= The team members of the system assigned by the Super Adminpanel_user
= The panel for the customers
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.
There are quite a few steps you need to take to add/edit/delete variants, and I'll walk you through all of them:
- Create migration to
add/edit/delete
database variants. - Update the
ProductVariant.php
factory if needed. As of now only thesize
andcolor
variants are assigned on the initial database seed just to keep things simple. - Add the
Enum
for the newly created variant inApp/Enums
. To keep things simple, the enum can be named the same name as the database column, but you can name it whatever you want. - Update the
getForm()
function inProductVariant.php
model, add/edit/delete the desired variants. - Update the
$table
function inProductVariantResource.php
, add/edit/delete the desired variants. - Update the
$table
function inVariationsRelationManager.php
, add/edit/delete the desired variants. - Add/Update/Delete the newly created Enum name inside
config/enums.php
. - Update '$casts' on the
ProductVariant.php
model
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.
WittyWorkflow includes a comprehensive appointment scheduling system that integrates with email notifications and calendar systems.
The appointment system consists of several key components:
- Models:
Appointment
andService
models manage the data structure - Booking Flow: Users select services, available time slots, and complete bookings
- Notifications: Automatic emails for booking confirmation, reminders, and updates
-
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
-
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
-
Configure Email Templates:
- Customize email templates for appointment confirmations and reminders
- Set up notification preferences for both staff and customers
Appointments can be managed through the Filament admin panel:
-
View Appointments:
- See all upcoming appointments in a calendar or list view
- Filter by date, service, or status
-
Create Appointments:
- Add appointments manually for walk-in customers
-
Update Appointments:
- Reschedule appointments as needed
- Change service or duration
- Add notes or special requirements
-
Cancel Appointments:
- Cancel with automatic notification to the customer
- Optionally offer rebooking options
The appointment system can be customized in several ways:
- Booking Rules: Modify booking rules in
app/Models/Appointment.php
- Email Templates: Customize email templates in
resources/views/emails/appointments/
- Booking Form: Extend the booking form in
resources/views/livewire/appointment-form.blade.php
WittyWorkflow comes with a comprehensive test suite covering models, features, and integrations.
# Run all tests
php artisan test
# Run specific test suite
php artisan test --testsuite=Feature
# Run specific test
php artisan test --filter=HeroTest
- Unit Tests: Test individual components in isolation
- Feature Tests: Test complete features and user workflows
- Browser Tests: Test UI interactions using Laravel Dusk (if installed)
The test files are organized in the following directories:
tests/Unit/
: Unit tests for individual classes and methodstests/Feature/
: Feature tests for complete functionalitytests/Feature/Models/
: Tests for model functionality
When adding new features, create corresponding tests in the appropriate directory:
- Model tests in
tests/Feature/Models/
- Feature tests in
tests/Feature/
- Browser tests in
tests/Browser/
(if using Dusk)
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]);
}
WittyWorkflow is designed to be highly customizable without modifying core files.
- Colors: Modify the color scheme in
tailwind.config.js
- Typography: Change fonts and text styles in
resources/css/app.css
- Layouts: Customize layouts in
resources/views/layouts/
- Custom Resources: Add new Filament resources in
app/Filament/Resources/
- Custom Widgets: Create dashboard widgets in
app/Filament/Widgets/
- Custom Fields: Add custom form fields in
app/Forms/Components/
-
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
-
Custom User Roles:
- Extend the Shield configuration to add new roles
- Define permissions for the new roles
- Create role-specific dashboards or views
-
Payment Gateway Integration:
- Add alternative payment methods beyond Stripe
- Create payment gateway service classes
- Integrate with checkout process
- PHP 8.1+
- Nginx or Apache
- MySQL 5.7+ or PostgreSQL 10+
- Composer
- Node.js and NPM (for asset compilation)
-
Set up your web server and database:
- Configure Nginx/Apache with proper PHP settings
- Create a database for your application
-
Clone the repository to your server:
git clone https://github.com/kristi11/ww-filament.git /path/to/your/site
-
Install dependencies:
composer install --no-dev --optimize-autoloader npm install && npm run build
-
Set up environment variables:
- Copy
.env.example
to.env
- Configure database, mail, and other settings
- Generate application key:
php artisan key:generate
- Copy
-
Run migrations:
php artisan migrate
-
Set up task scheduling: Add this to your crontab:
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
-
Configure caching:
php artisan config:cache php artisan route:cache php artisan view:cache
- Laravel Forge: One-click deployment with automatic SSL
- Digital Ocean: Using the App Platform
- AWS: Deploying with Elastic Beanstalk
WittyWorkflow implements multiple security features to protect your application and data.
- Standard email/password authentication
- Two-Factor Authentication (2FA)
- One-Time Password (OTP)
- Role-based access control via Filament Shield
- Permission management through the admin panel
- Policy-based authorization for fine-grained control
- Keep all dependencies updated
- Enable HTTPS in production
- Implement proper CORS policies
- Use environment variables for sensitive information
- User data is encrypted where appropriate
- Passwords are hashed using bcrypt
- CSRF protection is enabled for all forms
- XSS protection through proper output escaping
- Enable Redis caching in
.env
:CACHE_DRIVER=redis
- Use model caching for frequently accessed data
- Implement view caching for complex templates
- Add indexes to frequently queried columns
- Use eager loading to prevent N+1 query issues
- Consider database table partitioning for large datasets
- Use production builds:
npm run build
- Enable HTTP/2 on your web server
- Implement a CDN for static assets
- Use Laravel Telescope for development debugging
- Implement Laravel Horizon for queue monitoring
- Consider New Relic or Blackfire for production monitoring
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
- Create separate dashboards for each user role
- Add Filament Shield for managing user roles and permissions
- Create business information resources (appointments, services, users etc. )
- Add socials resource for referencing business's social profiles
- Add CRUD functionality to sections of the public page for a more controlled and customizable experience
- Add Hero animations
- Add footer resources to give users an easy way to add their policies, FAQ and other business related information
- Add flash notifications and email notifications for appointment changes
- Add shop for purchases
- Improve visuals (ongoing effort)
- Add Announce package to announce different messages to system users
- Add Themes package to give users more options on system layout and design
- Add Filament Breezy for 2-factor authentication and better profile updating
- Add Language-switch to support different languages
- Add Spatie Laravel Health to check how the app is running.
- Add One Time Passwords (OTP) for an extra added layer of security
- 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
- Add auto logout plugin where you can set an auto logout timer to bump up security
- Niche Marketplace Features: Add producer/retailer panels, delivery tracking for projects like artisanal food hubs (Help Wanted).
- Enhanced E-commerce: Stripe Connect payouts, shipping integrations (e.g., USPS API).
- Core Polish: Improve visuals, optimize dashboard data (Ongoing).
- Dev Tools: Add Laravel Reverb for live order tracking, Excel export for orders.
- User Experience: Theme switcher UI, email template builder (Help Wanted).
- Analytics: Basic admin stats (e.g., sales, user growth).
Note
The following are the known issues that need addressing and I hope that the community will step in and work on them:
- Cart items don't get sent from
session id
touser_id
if the user was logged out when placing the order but after filling out the cart logs in/registers for an account to continue with the order.
- For now as a workaround only logged-in users can add to cart.
Love open source? Help shape WittyWorkflow:
-
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
-
Create a feature branch:
git checkout -b feature/your-idea
-
Implement your changes:
- Follow the coding standards (PSR-12)
- Write or update tests for your changes
- Ensure all tests pass:
php artisan test
-
Commit your changes:
git commit -m "Add cool thing"
Use descriptive commit messages that explain what changes were made and why.
-
Push to your fork:
git push origin feature/your-idea
-
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
- Follow PSR-12 coding standards
- Use Laravel naming conventions
- Write descriptive commit messages
- Document public methods and classes
- Update the README.md with details of changes if applicable
- Update the CHANGELOG.md with details of changes
- The PR will be merged once reviewed and approved
Check Issues for tasks (e.g., cart bug)โemail tanellari@gmail.com with questions.
This project is distributed under the MIT License, one of the most permissive and widely used open source licenses.
- You can: Use the code commercially, modify it, distribute it, and use it privately
- You must: Include the original copyright notice and the license text in any copy of the software/source
- You cannot: Hold the authors liable for damages as the software is provided "as is"
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.
- Understanding the MIT License - A detailed explanation of the MIT license
- Open Source Initiative - The MIT License defined by the Open Source Initiative
- TLDRLegal MIT Explanation - A simplified explanation of what you can, cannot, and must do
Project Link: https://github.com/kristi11/ww-filament/
I've included a few of my favorite links to kick things off!