A comprehensive B2B cannabis marketplace platform built with Laravel, featuring business onboarding, compliance tracking, and multi-tenant architecture.

🚀 Features

Current Implementation (Phase 1)

Business Registration & Onboarding: Multi-step wizard with compliance requirements
User Management: Role-based access with admin approval workflow
License Verification: Cannabis license tracking with expiration monitoring
Document Management: Secure file uploads for business documents
Notification System: Real-time notifications with progress tracking
Dashboard: Business-specific dashboards with setup progress
Admin Panel: Filament-powered admin interface for business approval

Authentication & Security

Laravel Breeze-based authentication with /b/ business routing
Email verification and admin approval required
CSRF protection and secure session management
User approval workflow with notification system

UI/UX

Nexus dashboard theme with DaisyUI components
Responsive design with dark/light mode toggle
Clean, professional cannabis industry styling
Alpine.js for interactive components

🛠 Tech Stack

Layer	Technology
Backend	Laravel 12 (PHP 8.4)
Frontend	Blade Templates + Tailwind CSS
UI Framework	DaisyUI + Nexus Theme
Database	PostgreSQL 17
Cache/Queue	Redis 7
Authentication	Laravel Breeze
Admin Panel	Filament
Permissions	Spatie Laravel Permission
PDF Generation	DomPDF (barryvdh/laravel-dompdf)
Testing	Pest
Assets	Vite
Containerization	Docker + Laravel Sail
Versioning	CalVer (YYYY.MM-commit)

📋 Quick Start

Prerequisites

Choose your development approach:

Option A: Docker (Recommended)

Docker Desktop or Colima
Docker Compose
Git

Option B: Local PHP

PHP 8.4+
Node.js 22+
Composer 2.x
PostgreSQL 17
Redis 7

1. Clone & Install

git clone <repository-url> cannabrands
cd cannabrands
composer install
npm install

2. Environment Setup

cp .env.example .env
php artisan key:generate

3. Choose Your Development Environment

Option A: Docker with Laravel Sail (Recommended)

Laravel Sail provides a complete containerized environment with PostgreSQL, Redis, and Mailpit.

# Quick start using Makefile
make install        # Initial setup (first time only)
make dev            # Start all services
make migrate        # Run migrations
make dev-vite       # Start Vite dev server for hot module reloading

# Visit: http://localhost
# Mailpit (emails): http://localhost:8025

Using Makefile Commands (Recommended):

The project includes a comprehensive Makefile for easier Docker/Sail management. Run make help to see all available commands.

# Local Development
make dev            # Start Sail containers
make dev-down       # Stop Sail containers
make dev-build      # Rebuild Sail image
make dev-shell      # Open shell in container
make dev-logs       # View container logs
make dev-vite       # Start Vite dev server (run after 'make dev')

# Database
make migrate        # Run migrations
make migrate-fresh  # Fresh database with seeds
make migrate-prod   # Run migrations in production
make seed           # Run specific seeder (SEEDER=ClassName)

# Testing
make test           # Run test suite
make test-coverage  # Run tests with coverage

# Utilities
make install        # Initial project setup
make mailpit        # Open Mailpit UI in browser
make clean          # Clean Docker resources
make help           # Show all available commands

Advanced Usage:

# Run custom artisan commands
make dev-artisan CMD="queue:work"

# Run custom npm commands
make dev-npm CMD="run build"

# Run custom composer commands
make dev-composer CMD="require package/name"

Direct Sail Commands (if needed):

./vendor/bin/sail artisan ...   # Run artisan commands
./vendor/bin/sail composer ...  # Run composer
./vendor/bin/sail npm ...       # Run npm
./vendor/bin/sail php ...       # Run PHP scripts

Option B: Local PHP Development

Configure .env for local services:

DB_HOST=127.0.0.1  # or localhost
REDIS_HOST=127.0.0.1
MAIL_HOST=127.0.0.1

Start development:

php artisan serve
npm run dev

# Visit: http://localhost:8000

🎯 User Flows

Business Registration

Register at /b/register with basic business info
Email verification required
Admin approval via Filament panel
Multi-step onboarding wizard:
- Personal Information
- Business Details
- License Documentation
- Referral Information
- Review & Submit

Admin Workflow

Access admin panel at /admin
Review pending business applications
Approve/deny applications
Monitor license expiration dates
Manage user permissions

📊 Database Schema

Key Tables

users: User accounts with first_name, last_name, position
businesses: Business profiles with license and compliance data
business_user: Many-to-many relationship between users and businesses
notifications: Laravel notification system for user communications

Onboarding Data Flow

Session-based multi-step wizard
File uploads stored in storage/app/temp
Business creation upon final submission
Automatic notification triggers

🔧 Development Commands

Using Makefile (Recommended for Docker/Sail)

The project includes a comprehensive Makefile for easier development. All commands below work with Docker/Sail.

# Show all available commands with descriptions
make help

# Local Development
make dev            # Start Sail containers
make dev-down       # Stop Sail containers
make dev-build      # Rebuild Sail image
make dev-shell      # Open shell in container
make dev-logs       # View container logs
make dev-vite       # Start Vite dev server

# Database Operations
make migrate        # Run migrations
make migrate-fresh  # Fresh database with seeds
make migrate-prod   # Run migrations in production
make seed SEEDER=DevSeeder  # Run specific seeder

# Testing
make test           # Run test suite
make test-coverage  # Run tests with coverage

# Utilities
make install        # Initial project setup (first time)
make mailpit        # Open Mailpit UI in browser
make clean          # Clean Docker resources

# Advanced: Pass custom commands
make dev-artisan CMD="config:cache"
make dev-npm CMD="run build"
make dev-composer CMD="require vendor/package"

Direct Artisan Commands

For local PHP or when not using Makefile (prefix with ./vendor/bin/sail when using Sail):

# Database
php artisan migrate:fresh --seed  # Reset database
php artisan migrate                # Run pending migrations
php artisan migrate:status         # Check migration status

# Testing
./vendor/bin/pest                  # Run test suite
php artisan notifications:test 1  # Test notification system

# Cache Management
php artisan optimize:clear        # Clear all caches
php artisan config:cache          # Cache configuration
php artisan route:cache           # Cache routes
php artisan view:cache            # Cache views

# Versioning
php artisan version:update        # Update CalVer version

📁 Project Structure

├── app/
│   ├── Http/Controllers/
│   │   ├── OnboardingController.php      # Multi-step wizard
│   │   ├── BusinessAuthController.php    # Business authentication
│   │   └── NotificationController.php    # Notification API
│   ├── Models/
│   │   ├── User.php                      # Enhanced user model
│   │   └── Business.php                  # Business profiles
│   ├── Notifications/                    # Laravel notifications
│   └── Services/
│       └── BusinessProgressService.php   # Setup progress tracking
├── resources/
│   ├── views/
│   │   ├── onboarding/                   # Multi-step wizard views
│   │   ├── business/                     # Business-specific views
│   │   └── dashboard/                    # Dashboard layouts
│   └── js/app.js                         # Alpine.js configuration
├── docs/                                 # Comprehensive documentation
└── nexus-html@3.1.0/                    # Nexus theme reference templates

🐳 Docker & Containerization

Laravel Sail (Local Development)

Sail provides a complete containerized environment:

Service	Port	Purpose
Laravel App	80, 5173	PHP 8.4 application + Vite dev server
PostgreSQL 17	5432	Primary database
Redis 7	6379	Cache, sessions, queues
Mailpit	8025 (UI), 1025 (SMTP)	Email testing

Makefile commands (recommended):

make dev           # Start all services
make dev-down      # Stop all services
make dev-vite      # Start Vite dev server
make dev-logs      # View logs
make dev-shell     # Open shell in container
make dev-build     # Rebuild Sail image
make migrate       # Run migrations
make migrate-fresh # Fresh database with seeds

Direct Sail commands (if needed):

./vendor/bin/sail up -d      # Start all services
./vendor/bin/sail down        # Stop all services
./vendor/bin/sail ps          # Check service status
./vendor/bin/sail logs        # View logs

Production Deployment

Production uses optimized Docker containers with:

Multi-stage builds for minimal image size
Nginx + PHP-FPM for performance
Supervisor for queue workers
Health check endpoints
Automated deployment scripts

Makefile production commands:

make prod-build    # Build production Docker image
make prod-up       # Start production containers
make prod-down     # Stop production containers
make prod-restart  # Restart production containers
make prod-logs     # View production logs
make prod-shell    # Open shell in production container
make prod-vite     # Build production assets (for CI/CD)
make migrate-prod  # Run migrations in production

# Run custom artisan commands in production
make prod-artisan CMD="config:cache"

Quick deploy script:

./scripts/deploy.sh

See docker-compose.production.yml and Dockerfile for production configuration.

🏷️ Version Tracking & Traceability

The application automatically injects version metadata at Docker build time for complete traceability.

How It Works:

Docker images contain build metadata in version.env:

VERSION=dev (or 2025.10.2 for releases)
COMMIT=a1b2c3d (7-char git SHA)

Footer displays version to help identify deployed code:

Local development (clean): DEV sha-a1b2c3d (yellow highlight)
Local development (dirty): DEV sha-a1b2c3d-dirty (yellow highlight)
Docker dev build: DEV sha-a1b2c3d (yellow highlight)
Production release: v2025.10.2 (sha-a1b2c3d)

Docker Tag to Version Mapping:

Environment	Docker Tag	Internal Version	Footer Display
Local dev (clean)	N/A	`VERSION=dev` `COMMIT=a1b2c3d`	`DEV sha-a1b2c3d`
Local dev (dirty)	N/A	`VERSION=dev` `COMMIT=a1b2c3d-dirty`	`DEV sha-a1b2c3d-dirty`
Docker dev build	`dev`	`VERSION=dev` `COMMIT=a1b2c3d`	`DEV sha-a1b2c3d`
Docker dev build	`sha-a1b2c3d`	`VERSION=dev` `COMMIT=a1b2c3d`	`DEV sha-a1b2c3d`
Production release	`2025.10.2`	`VERSION=2025.10.2` `COMMIT=a1b2c3d`	`v2025.10.2 (sha-a1b2c3d)`
Production release	`latest`	`VERSION=2025.10.2` `COMMIT=a1b2c3d`	`v2025.10.2 (sha-a1b2c3d)`

Bug Tracking Workflow:

# User reports bug: "I'm on v2025.10.2"
# or "I'm on DEV sha-a1b2c3d"

# Checkout exact commit
git checkout a1b2c3d

# Reproduce bug
# Fix bug
# Deploy fix

For Local Development:

Version tracking is automatic! The application reads your git commit SHA directly:

Clean working directory: DEV sha-a1b2c3d
Uncommitted changes: DEV sha-a1b2c3d-dirty

How it works:

Docker: Reads from version.env (injected at build time)
Local dev: Reads from git directly (no file needed)
Automatically detects uncommitted changes

Why git SHA instead of "local"?

✅ Know exactly what code you're running
✅ Compare commits when debugging
✅ Switches automatically when you change branches
✅ Industry standard (Git, Docker, Kubernetes, etc.)
✅ The -dirty suffix warns you there are uncommitted changes

No setup required - just works!

📚 Documentation

Getting Started

Development Guide: Complete developer setup and workflow
- ✅ Standard/Hybrid Flow (PHP on host + Docker services)
- ✅ Local Kubernetes Development (k3d, minikube, kind, Docker Desktop K8s)
- Covers all local development approaches
Docker & Sail Guide: Laravel Sail development environment
- ✅ Laravel Sail Flow (All services in Docker)
- Quick start for containerized development

Deployment & DevOps

Deployment Workflow: Branching strategy, CI/CD pipeline, and deployment guide
Kubernetes Deployment: Production Kubernetes deployment guide (for DevOps/SRE)
- Production/Staging/Dev K8s clusters
- Not for local development (see DEVELOPMENT.md for local K8s)

Application Reference

Setup Guide: Detailed installation and configuration
API Reference: Complete API endpoint documentation
Database Schema: Database structure and relationships
Notifications: Notification system guide
App Overview: Project roadmap and architecture

Development Flow Options Summary

Flow	Document	Best For
Local PHP + Docker services	DEVELOPMENT.md	Daily development (fastest)
Laravel Sail (all Docker)	DOCKER.md	Environment consistency
Local Kubernetes (k3d/minikube)	DEVELOPMENT.md	Testing K8s deployments
Production Kubernetes	KUBERNETES_DEPLOYMENT.md	Production/staging clusters

🚀 Deployment

Docker Deployment (Recommended)

Prerequisites:

Docker & Docker Compose installed on server
.env file configured with production values
Git repository access

Quick Deploy:

./scripts/deploy.sh

This script will:

Pull latest code from git
Build production Docker image
Start containers with health checks
Run database migrations
Cache configuration files
Verify application health

Manual Docker Deployment:

# Build production image
docker build -t cannabrands/app:latest -f Dockerfile .

# Start production containers
docker-compose -f docker-compose.production.yml up -d

# Run migrations
docker-compose -f docker-compose.production.yml exec -T app php artisan migrate --force

# Cache configurations
docker-compose -f docker-compose.production.yml exec -T app php artisan config:cache
docker-compose -f docker-compose.production.yml exec -T app php artisan route:cache
docker-compose -f docker-compose.production.yml exec -T app php artisan view:cache

Traditional Deployment

For non-Docker deployments:

Production Checklist:

Set APP_ENV=production and APP_DEBUG=false
Configure production database
Set up SMTP for notification emails
Run npm run build for optimized assets
Configure web server (Apache/Nginx)
Set up SSL certificate
Configure file storage for document uploads

Key Commands:

composer install --no-dev --optimize-autoloader
npm run build
php artisan config:cache
php artisan route:cache
php artisan view:cache

Environment Variables

Production .env template:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

DB_CONNECTION=pgsql
DB_HOST=pgsql  # or your database host
DB_PORT=5432
DB_DATABASE=cannabrands
DB_USERNAME=sail
DB_PASSWORD=your-secure-password

CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis
REDIS_HOST=redis  # or your Redis host

See .env.production.example for complete configuration template.

🔒 Security Notes

All business documents stored securely with path-only database references
CSRF protection on all state-changing requests
User-scoped data access with proper authorization
License compliance tracking with expiration monitoring
Admin approval required for all business accounts

🏗 Future Roadmap

Phase 2: Marketplace Features

Product catalog and inventory management
Order processing and fulfillment
Business-to-business messaging
Payment integration

Phase 3: Advanced Features

Multi-tenancy implementation
Advanced analytics and reporting
Mobile app development
Third-party integrations

🤝 Contributing

Follow PSR-12 coding standards
Use Pest for testing new features
Reference /docs/APP_OVERVIEW.md for development approach
All features should maintain strong compliance and regulatory focus

Last Updated: October 2025 Version: 2025.10 (CalVer) License: Proprietary

Test branch protection

Languages

Blade 49.8%

PHP 48.8%

JavaScript 1%

CSS 0.2%

Shell 0.1%