README

BookFlow

A portfolio-grade, multi-tenant SaaS booking system built with modern PHP.

Stack

• PHP 8.4+ (strict types, no framework)
• MySQL 8.0
• Vanilla JavaScript
• Docker for development

Architecture

• Domain-Driven Design: Pure domain logic, no infrastructure leakage
• Layered Architecture: Domain → Application → Infrastructure → HTTP
• Multi-Tenancy: Single database, shared schema, tenant_id enforced everywhere
• Testability First: All business logic is unit-testable

Key Features

• Booking creation with conflict detection
• Availability rules enforcement
• Google Calendar integration
• Background job processing for async tasks
• Timezone-safe time handling

Getting Started

Prerequisites

• Docker & Docker Compose

Installation

# Clone the repository
git clone https://github.com/ricvale/bookflow.git
cd bookflow

# Start the Docker environment
docker compose up -d

# Install dependencies
docker compose exec app composer install

# Run tests
docker compose exec app ./vendor/bin/phpunit

Access

• Application: http://localhost:8000
• MySQL: localhost:3306 (user: bookflow, password: bookflow)

Deployment & Sharing

• 🚀 Instant Public Demo (Easiest): This project includes a Zero-Config Cloudflare Quick Tunnel. Just run docker compose up -d and see Cloudflare Quick Tunnel to get your public URL instantly. No account or credit card required.
• Public Cloud Hosting: For always-on hosting, see our Truly Free Hosting Options.

Project Structure

bookflow/
├── docs/               # Architecture and domain documentation
├── skills/             # AI-agent skills (agentskills.io compliant)
│   ├── booking/
│   ├── tenancy/
│   ├── authentication/
│   ├── availability/
│   └── calendar-integration/
├── src/                # Backend (PHP)
│   ├── Domain/        # Pure business logic
│   ├── Application/   # Use cases and policies
│   ├── Infrastructure/# MySQL, APIs, logging
│   └── Http/          # Controllers and routing
├── frontend/           # Frontend (Vanilla JS) - SEPARATE
│   ├── src/           # JavaScript modules
│   ├── public/        # HTML entry point
│   └── assets/        # CSS, images
├── tests/
│   ├── Unit/          # Domain and application tests
│   └── Integration/   # Infrastructure tests
├── public/            # Backend web entry point
└── docker/            # Docker configuration

Frontend/Backend Separation

• Backend: PHP API (REST, JSON)
• Frontend: Vanilla JavaScript (can be deployed separately)
• Communication: HTTP only (JWT for auth)
• No shared code: Completely decoupled

AI-Agent Ready

This project follows agentskills.io for AI-friendly documentation:

• Each domain context has a SKILL.md file
• Progressive disclosure (lightweight descriptions, detailed on-demand)
• Clear constraints, edge cases, and examples
• See skills/README.md for details

Design Principles

1. Explicit over Implicit: No magic, no hidden behavior
2. Domain Purity: Business logic has zero infrastructure dependencies
3. Tenant Isolation: tenant_id is never accepted from user input
4. Type Safety: Strict types everywhere
5. Small Classes: Single responsibility, focused methods

Testing

# Run all tests
docker compose exec app ./vendor/bin/phpunit

# Run only unit tests
docker compose exec app ./vendor/bin/phpunit --testsuite=Unit

# Run with coverage
docker compose exec app ./vendor/bin/phpunit --coverage-html coverage

Documentation

• Architecture & Design
  • Architecture - System design and layers
  • Multi-Tenancy - Tenant isolation strategy
  • Domain Glossary - Domain terminology
• Development
  • Testing Guide - Unit, integration, and E2E testing
  • Debugging Guide - Xdebug setup and troubleshooting
  • Contributing - How to contribute
• Operations
  • Cloudflare Sharing - Share your local instance
  • Free Deployment - Truly free hosting options
  • Deployment Guide - Production deployment
  • Monitoring - Observability and alerting
• AI-Agent Skills
  • Skills Index - AI-friendly documentation
  • Booking Skill
  • Tenancy Skill
  • Authentication Skill
  • Availability Skill
  • Calendar Integration Skill

DevOps & CI/CD

Makefile Commands

make help          # Show all available commands
make install       # Install dependencies
make test          # Run all tests
make lint          # Run code quality checks
make up            # Start Docker services
make down          # Stop Docker services

GitHub Actions

• CI Pipeline: Runs on every push and PR
  • PHPUnit tests with coverage
  • PHPStan static analysis (level 8)
  • PHP-CS-Fixer code style checks
  • Security audit (composer audit)
  • Docker build verification

Code Quality Tools

• PHPStan: Static analysis at level 8
• PHP-CS-Fixer: PSR-12 code style enforcement
• PHPUnit: Unit and integration testing
• Codecov: Test coverage tracking

License

MIT