Cannabrands B2B Platform

A LeafLink-style cannabis marketplace platform built with Laravel, featuring business onboarding, compliance tracking, and multi-tenant architecture foundation.

---

🚀 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

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

Admin Workflow

1. Access admin panel at /admin
2. Review pending business applications
3. Approve/deny applications
4. Monitor license expiration dates
5. 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:

1. Pull latest code from git
2. Build production Docker image
3. Start containers with health checks
4. Run database migrations
5. Cache configuration files
6. 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 LeafLink-style compliance focus

---

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

Test branch protection