Download the PHP package padosoft/laravel-flow-admin without Composer

📚 Table of Contents

• ✨ Why this package
• 🎯 Features
• 📸 Screenshots
• 📦 Requirements
• 🚀 Quick Start (5 minutes)
• 📖 Step-by-Step Setup
  • 1. Install the underlying engine
  • 2. Install the admin panel
  • 3. Publish assets and config
  • 4. Configure middleware & routes
  • 5. Wire your authorizer
  • 6. Visit the panel
• ⚙️ Configuration
• 🔒 Authorization (mutations)
• 🎨 Customization
• 🧪 Demo Mode (no DB needed)
• 🗺️ Routes
• 🏛️ Architecture
• 🤖 AI Vibe Coding Pack
• ⚖️ Comparison
• 🛣️ Roadmap
• ✅ Quality Gates
• 🤝 Contributing
• 🔐 Security
• 📜 License
• 💜 Credits

✨ Why this package

padosoft/laravel-flow is intentionally headless — a deterministic, queue-driven workflow engine you can drop into any Laravel app.

laravel-flow-admin is the operator console for it. A production-style control plane for runs, approvals, outbox webhooks and configuration — without leaking the engine's internal namespaces into your app.

Think Horizon for queues, Pulse for metrics — and Flow Admin for the lifecycle of long-running, multi-step business workflows.

🎯 Features

• 📊 Overview dashboard — KPI tiles, sparklines, recent runs, queue health, error rate.
• 🏃 Runs index & detail — filterable list, full timeline (timeline / Gantt / DAG), payload diff, retry/cancel actions.
• ✅ Approvals inbox — pending decisions with one-click approve / reject through your own authorizer.
• 📤 Webhook outbox — delivery state, replay failed jobs, inspect headers/payloads.
• 📋 Flow definitions — registered workflows, version, last activity at a glance.
• ⚡ ⌘K command palette — jump anywhere in two keystrokes.
• 🎨 Pixel-perfect dark + light themes — persisted in cookie, switchable per user.
• 🛡️ Deny-by-default authorizer — every mutation goes through your ActionAuthorizer. No accidents.
• 🔁 Auto-refreshing pages — configurable polling (/flow/api/live).
• 🧱 Adapter pattern — eloquent for prod, array for demos / E2E (deterministic seed-42 fixtures).
• 🧪 Battle-tested — 101 PHPUnit tests, 18 Playwright scenarios across Chromium / Firefox / WebKit.
• 📦 Zero-coupling — built on a public Contracts\* surface; engine internals stay @internal.

📸 Screenshots

📦 Requirements

💡 You do not need Node.js to use this package. Pre-built assets ship inside the package and are publishable via vendor:publish.

🚀 Quick Start (5 minutes)

That's it. The panel is read-only by default (deny-all authorizer) so you can safely browse production data on day 1, then opt-in to mutations when you've wired your permission rules.

📖 Step-by-Step Setup

1. Install the underlying engine

laravel-flow-admin is a UI on top of padosoft/laravel-flow. If you don't already have it, install it first:

This creates the flow_runs, flow_steps, flow_approvals, flow_webhook_outbox and related tables that this admin panel reads from.

📖 Full engine docs: github.com/padosoft/laravel-flow

2. Install the admin panel

The service provider is auto-discovered. Routes, views, config and migrations are loaded out-of-the-box from the package.

3. Publish assets and config

⚠️ Don't skip flow-admin-assets in production. The panel relies on the published CSS/JS bundle.

4. Configure middleware & routes

By default the panel mounts at /flow and runs through web,auth middleware. Override with environment variables:

🛡️ If you set FLOW_ADMIN_MIDDLEWARE="" we fall back to ['web'] instead of leaving the panel unauthenticated. Setting it empty was a known footgun, so we close it explicitly.

5. Wire your authorizer

The panel ships with DenyAllAuthorizer so every mutation (resume, reject, replay, cancel, retry-webhook) is blocked by default. To enable mutations, implement your own:

Bind it in AppServiceProvider::register():

…or set 'authorizer' => App\Flow\AdminAuthorizer::class in config/flow-admin.php.

6. Visit the panel

Open http://localhost:8000/flow and you should see the dashboard. Press ⌘K (or Ctrl+K) anywhere to open the command palette.

⚙️ Configuration

All keys live in config/flow-admin.php. They are also overridable via environment variables.

🔒 Authorization (mutations)

Every mutation route (resume, reject, replay, cancel, retry-webhook) consults your ActionAuthorizer before the controller runs. This is non-negotiable: there is no "global admin" bypass and no way to short-circuit the gate from a Blade view.

Public extension surface (semver-stable from v0.1.0 →):

• Padosoft\LaravelFlowAdmin\Contracts\ActionAuthorizer
• Padosoft\LaravelFlowAdmin\Contracts\ReadModelAdapter
• Padosoft\LaravelFlowAdmin\Contracts\ViewModelFactory (and family)
• config/flow-admin.php keys
• Publish tags: flow-admin-config, flow-admin-views, flow-admin-assets
• Route names: flow-admin.*

Everything under Adapters\, Http\Controllers\, Support\, ViewModels\ is internal and may change between minor versions until v1.0.

🎨 Customization

Override Blade views

Edit anything under resources/views/vendor/flow-admin/. Component slots and named layout sections are preserved across upgrades.

Override CSS tokens

The published bundle exposes CSS custom properties for colors, radii, spacing and font sizing. Wrap the panel in a custom theme by overriding tokens:

Switch theme programmatically

🧪 Demo Mode (no DB needed)

For showcases, screenshots, or end-to-end tests you can bypass the database entirely:

The ArrayReadModelAdapter produces deterministic fixtures (seed=42) so KPI numbers, run IDs and timelines are reproducible across screenshots and Playwright runs.

🗺️ Routes

All routes live under the configured prefix (default /flow) and the flow-admin.* route-name namespace.

🏛️ Architecture

Design source-of-truth lives under .design-source/project/ (pixel reference) and is enforced through Playwright visual regression on chromium / firefox / webkit.

🤖 AI Vibe Coding Pack

This repository ships a contributor pack under .claude/:

• Rules — Laravel 13 defaults, admin-panel UX, query optimization, naming conventions, exception handling, logging security.
• Skills — orchestrators for create-admin-interface, playwright-enterprise-tester, copilot-pr-review-loop, pre-push-self-review, test-count-readme-sync.
• Runbooks — macro/subtask branch workflow used during initial implementation.

If you build with Claude Code or another agent, copy .claude/ into your downstream project for a head start.

⚖️ Comparison

🛣️ Roadmap

• [x] v0.1 — core pages, eloquent + array adapters, theme cookie, ⌘K palette, Playwright matrix.
• [x] v0.1.1 — public release hardening, README polish, GitHub release artifacts.
• [ ] v0.2 — bulk actions on runs, saved filter presets, CSV/JSON export.
• [ ] v0.3 — Pulse-style sparkline cards, alerting hooks.
• [ ] v1.0 — frozen public surface, SemVer guarantees, downstream-stable Adapters.

✅ Quality Gates

Every push runs through this gate (matrix php: 8.3, 8.4 × laravel: 13):

Latest local run: 101 tests / 584 assertions / 18 E2E scenarios passed.

🤝 Contributing

PRs welcome! Please:

1. Open an issue first for non-trivial changes.
2. Branch from main as task/<short-name> or subtask/<short-name>.
3. Run the full local gate (above) before pushing.
4. Add tests — unit, feature, or Playwright depending on the change.
5. Update docs/PROGRESS.md if your PR closes a roadmap item, and docs/LESSON.md if you discover a reusable insight.

See CODE_OF_CONDUCT.md.

🔐 Security

If you discover a security vulnerability, please do not open a public issue. Email [email protected] directly. See SECURITY.md for our disclosure policy.

📜 License

Apache-2.0 © Padosoft. See LICENSE for the full text.

💜 Credits

• Padosoft — package author and maintainer.
• padosoft/laravel-flow — the headless workflow engine this panel operates.
• Laravel, Alpine.js, Vite, Playwright — the giants whose shoulders this is built on.