README

EvoLayer Base

A fully working AI application layer for the official Laravel AI SDK. Structured-output streaming, ontology-driven events, and production-ready React surfaces — delivered as a project template.

Documentation · Quick Start · Package Repo · YouTube · Changelog

Developer preview: Both xuple/evolayer-base and xuple/evolayer-base-starter are public, MIT-licensed, pre-1.0 packages on GitHub and Packagist. The current public install line is starter v0.1.19 with xuple/evolayer-base v0.1.9.

The Promise

EvoLayer Base gives you the best of both worlds: a clean, manageable starting point with continuous upstream updates, and the freedom to take total control exactly when you need it. It is a working AI application layer delivered through a project template.

• You own your routes, models, config, branding, and any surface you eject.
• The application layer manages the complex AI runtime, ontology, commands, and example surfaces behind the scenes. It keeps them updated automatically via composer evolayer:resync so your codebase stays clean.
• Ejecting empowers you. Whenever you want to deeply customize a managed surface, simply run php artisan evolayer:eject <surface>. You take full ownership of the code, and we'll step out of the way.

Read the full Promise and Framework Contract.

Quick Start

composer create-project xuple/evolayer-base-starter my-app
cd my-app
npm install && npm run build
php artisan serve

composer create-project runs the post-create hook automatically — generating your app key, creating an SQLite database, running migrations and seeders, compiling the Wayfinder and ontology caches, and adding generated-app identity notes for humans and agents. Log in with test@example.com / password to explore every surface immediately.

Cloned the repo directly? Run composer setup instead. Hosting behind Nginx? See docs/local-dev-hosting.md. For generated-app identity behavior, see docs/migration/generated-app-identity.md.

Why EvoLayer Base?

• Structured AI Streaming — Real-time structured-output streaming via the laravel/ai SDK. Defaults to Gemini; the SDK also supports OpenAI, Anthropic, DeepSeek, Groq, xAI, Mistral, and Ollama. (ThreadStudio runtime-approves Gemini + OpenAI today — see AI providers.)

• Working AI Surfaces, Not Stubs — ThreadStudio, PRD Studio, AI contact triage, voice input, and inline text assist ship functional — not as placeholder wireframes.

• Ontology-Driven Events — An ontology.yaml model compiles to typed SSE events and projections, giving your real-time UI a schema instead of ad-hoc event strings.

• Feature Flags, Not Bloat — Every example surface toggles independently via EVOLAYER_BASE_EXAMPLE_* env flags. Disable what you don't need; routes and sidebar entries disappear.

• Reproducible Installs — Committed composer.lock, exact-pinned framework while 0.x, deterministic create-project. Two installs of the same version are identical.

• Agent-Ready Tooling — Pre-wired for Claude Code, Codex, OpenCode, and Cursor via Laravel Boost with MCP, skills, and search-docs.

Choose Your Path

How the pieces fit

It gives you a full Laravel application from day one — auth, host Inertia pages, React components, Tailwind styling, EvoLayer-published examples, config, seeders, and tests are all available to adapt. (Note: The starter is built on the foundation of the official laravel/react-starter-kit.)

Framework Contract: For the strict definition of what the framework manages versus what you own, see the EvoLayer Framework Contract in the upstream package.

Features

Each bundled example surface is gated by an EVOLAYER_BASE_EXAMPLE_* flag in .env; substrate features use the EVOLAYER_BASE_FEATURE_* prefix. Set a flag to false to drop that surface's routes and sidebar entry.

AI providers

EvoLayer Base uses the laravel/ai SDK for structured-output streaming. It defaults to Gemini, but supports a vast ecosystem including OpenAI, Anthropic, DeepSeek, Groq, xAI, Mistral, and Ollama. To enable AI features, set your provider's API key in .env (GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.), then verify structured streaming works end to end:

php artisan evolayer:ai:stream-check gemini

Provider status: ThreadStudio's runtime-approved (directly-verified) providers are Gemini (default) and OpenAI — both pass evolayer:ai:stream-check end to end with the committed laravel/ai patch, and only these two are selectable as AI_THREAD_STUDIO_PROVIDER. Anthropic's structured-streaming path currently returns zero TextDelta events and an empty final payload, so it is diagnostic-eligible but blocked for ThreadStudio runtime / pending re-verification — exercise it with evolayer:ai:smoke-test anthropic (the non-streaming path passes), but it is not runtime-approved for selection. NVIDIA / OpenCode / OpenRouter are likewise router-backed diagnostic-eligible probe candidates, not runtime-approved. See patches/README.md for the verification matrix.

The laravel/ai patch

The starter ships patches/laravel-ai-structured-streaming.patch, applied automatically via cweagans/composer-patches on composer install. It enables structured-output streaming until upstream laravel/ai ships the fix. See patches/README.md for the rationale and upstream-PR tracking.

If streaming misbehaves, run php artisan evolayer:doctor — it verifies the patch marker along with the rest of the install.

Re-syncing the package frontend

The EvoLayer React stubs are committed so the repo clones and builds without a publish step. To pull a newer xuple/evolayer-base release:

composer update xuple/evolayer-base
composer evolayer:resync

evolayer:resync is manifest-safe — it updates pristine stubs, keeps host-modified ones, and skips ejected surfaces (--force to overwrite local edits, --dry-run to preview). Do not edit files under vendor/xuple/evolayer-base. Fix package internals upstream, then composer update + composer evolayer:resync here.

To add Base to an existing app instead, use php artisan evolayer:install — you don't need that command in this starter, its work is already pre-applied.

What's pre-applied

The package publishes most of its surface, but a few edits must live in host files. These are already applied:

• Middleware — shares the evolayer.base.{examples,features,brand} Inertia prop via EvoLayerProps::base().
• User model — adds Spatie HasRoles for the admin gate.
• Sidebar — renders enabled example pages via useExampleNavItems().
• Types — types the evolayer shared prop.
• Seeders — seeds the AI capability ledger and admin demo user.
• Spatie migrations — committed with ULID-compatible morph columns for EvoLayer models.

Social previews

Public preview defaults live in config/site.php, controlled by SITE_* and SOCIAL_* variables in .env. Public pages use PublicLayout / SiteHead for title, canonical, robots, Open Graph, X/Twitter, and JSON-LD. See .env.example for the full set.

Two opt-in knobs (blank by default, so output is unchanged until set):

• Local-business structured data — set SITE_JSONLD_TYPE (one or more schema.org types, comma-separated) with optional SITE_JSONLD_TELEPHONE / _EMAIL / _AREA_SERVED / _PRICE_RANGE / _SAME_AS to emit a server-rendered business node in the JSON-LD graph.
• Asset cache-busting — set SITE_ASSET_VERSION and wrap public asset paths with the useVersionedAsset() hook to append a global ?v= token, so replaced images are picked up past a CDN.

Tooling

• composer dev — run server, queue, logs, and Vite together.
• php artisan evolayer:doctor — health-check the install.
• npm run types:check / npm run build (client + SSR) / composer lint / composer test.
• docs/local-dev-hosting.md — Nginx/PHP-FPM hosted-dev checklist, tempnam() troubleshooting, and env-driven Vite port/origin HMR guidance.

The starter is pre-wired for AI coding agents (Claude Code, Codex, OpenCode, Cursor) via Laravel Boost: AGENTS.md / CLAUDE.md carry the starter-specific boundaries followed by Boost's framework guidelines, and .mcp.json / .codex/config.toml / opencode.json register php artisan boost:mcp. Skills live under .claude/skills/ and .agents/skills/. Boost is a require-dev dependency; the MCP layer is only available with dev dependencies installed.

The test runner is Pest 4 (php artisan test), layered on PHPUnit 12. New tests use Pest's it() / test() style (php artisan make:test --pest {name}); existing PHPUnit Tests\TestCase classes still run under Pest, so migration is opportunistic.

Where this sits in the EvoDevOps family

EvoLayer Base is the AI / ontology / blocks substrate: a Laravel + Inertia + React layer that turns the laravel/ai SDK into a structured-output streaming surface, with an ontology.yaml-driven event/projection model and a small block library on top. This starter is the composer create-project entry point for Base. The package itself is xuple/evolayer-base under the evolayer.base.* config and route namespace.

Sibling EvoDevOps layers (evolayer.commerce.*, evolayer.saas.*, evolayer.rls.*, …) are planned as separate packages with their own starter repos following the same pattern; they will not ship inside this Base starter. evodevops.com is the editorial / teaching home for the family; evodevops.com/evolayer-base/docs is the canonical Base documentation root.

Project Status

EvoLayer is pre-1.0. Base and the starter are free/public MIT projects published on GitHub and Packagist. See RELEASE.md and CHANGELOG.md.

Built on the Laravel React Starter Kit · Licensed under MIT