Federated from workspace · PRD-001 · Dental Clinic Revenue Operating System/docs/development/LOCAL_DEVELOPMENT_RUNTIME.md Do not edit canonical truth here — update the source repo, then re-run npm run docs:sync.

ZAIXOS Local Development Runtime

Status: FROZEN · Tag: v5.2-local-development-runtime
Authority: docs/releases/v5.2-local-development-runtime.md
Related frozen layers: FROZEN_ENGINEERING_LAYERS.md

Purpose

The Local Development Runtime is the official ZAIXOS engineering standard for running Consumer #1 (Dental Clinic ROS) on a developer machine. It orchestrates PHP, queue, logs, Vite, and optional embedded web server startup without shell wrappers or fragile process managers.

This layer is frozen. Changes require architectural review — see FROZEN_ENGINEERING_LAYERS.md.

Quick start

bash

composer install
npm install
cp .env.example .env
php artisan key:generate
php artisan migrate --seed
php artisan zaixos:setup-local --install

composer run dev    # equivalent: bin/zaixos dev

Runtime architecture

mermaid

flowchart TB
    subgraph entry [Entry points]
        BIN["bin/zaixos"]
        COMP["composer run dev"]
    end

    subgraph router [Command router]
        DEV[dev]
        STATUS[status]
        DOCTOR[doctor]
        FREEZE[freeze]
    end

    subgraph orchestrator [ZaixosLocalDevelopmentOrchestrator]
        PROV["LocalDevelopmentProviderContract"]
        SERVE["artisan serve optional"]
        QUEUE[queue:listen]
        PAIL[pail]
        VITE[vite]
    end

    subgraph artisan [Artisan commands]
        SETUP[zaixos:setup-local]
        VALIDATE[zaixos:validate-env]
        DOC[zaixos:doctor]
        STAT[zaixos:status]
        FLOC[zaixos:freeze-local]
        FCFG[zaixos:freeze-config]
    end

    COMP --> BIN
    BIN --> DEV
    BIN --> STATUS
    BIN --> DOCTOR
    BIN --> FREEZE
    DEV --> orchestrator
    PROV --> SERVE
    STATUS --> STAT
    DOCTOR --> DOC
    FREEZE --> FLOC

Components

Component	Location	Role
Entry router	`bin/zaixos`	Canonical CLI; dispatches subcommands
Orchestrator	`app/Modules/Saas/.../Runtime/ZaixosLocalDevelopmentOrchestrator.php`	Manages process stack; uses `PHP_BINARY` for all Artisan children
Provider contract	`LocalDevelopmentProviderContract`	DNS/platform integration; controls embedded web server
Provider resolver	`LocalDevelopmentProviderResolver`	Auto-detects Herd, Valet, Docker, dnsmasq, manual, etc.
Doctor	`ZaixosLocalDoctor` + validators	Deep diagnostics (PASS / WARNING / FAILED)
Status	`ZaixosLocalRuntimeStatusReporter`	Lightweight operational snapshot
Freeze verifier	`ZaixosLocalDevelopmentFreezeVerifier`	Read-only architecture + machine readiness gate

Provider abstraction

Each provider implements LocalDevelopmentProviderContract:

shouldStartEmbeddedWebServer() — When false, the orchestrator skips php artisan serve (future: Herd/Valet/Docker serve the app directly). Default: true (current behavior).
inspect() / install() — DNS and platform-specific setup.
key() / label() / priority() — Registry and auto-detection.

Registered providers live under app/Modules/Saas/Application/Services/LocalDevelopment/Providers/.

Official commands

`bin/zaixos`

Canonical local runtime entry point.

Subcommand	Action
`dev` (default)	Start development stack
`status`	Delegate to `php artisan zaixos:status`
`doctor`	Delegate to `php artisan zaixos:doctor`
`freeze`	Delegate to `php artisan zaixos:freeze-local`
`help`	Usage reference
`logs`, `restart`, `stop`	Reserved — not implemented

bash

bin/zaixos dev
bin/zaixos status
bin/zaixos doctor
bin/zaixos freeze

Deprecated: bin/zaixos-dev.php forwards to bin/zaixos dev with a deprecation notice.

`composer run dev`

Invokes @php bin/zaixos dev. Starts:

server — php artisan serve :8000 (when provider allows embedded server)
queue — php artisan queue:listen
logs — php artisan pail
vite — npm run dev / local node_modules/.bin/vite

When ports are ready, runs php artisan zaixos:dev-summary once (informational; never stops the stack).

Environment markers set by the orchestrator:

ZAIXOS_PHP — PHP binary used for all subprocesses
ZAIXOS_DEV_ORCHESTRATOR=1 — Indicates orchestrator-managed runtime

`php artisan zaixos:setup-local`

Installs local DNS, provider configuration, and wildcard tenant routing. Required once per machine:

bash

php artisan zaixos:setup-local --install

Uses the active Local Development Provider (Herd, dnsmasq, Docker, etc.).

`php artisan zaixos:validate-env`

Validates .env alignment with config/*.php and ZAIXOS domain rules. No system modifications.

`php artisan zaixos:doctor`

Diagnostic tool. Runs focused validators:

PHP runtime, environment, platform, DNS, queue, mail, database, session, storage, scheduler, tenancy

Outputs PASS / WARNING / FAILED with fix hints. Use when something is broken.

`php artisan zaixos:status`

Operational overview. Displays current runtime state only:

PHP, Database, Queue, Mailpit, Vite, Scheduler, Provider, Environment

No deep validation. Always exits successfully. Use for a quick “what is running?” check.

`php artisan zaixos:freeze-local`

Freeze verification gate. Read-only checks for:

bin/zaixos, composer dev script, orchestrator architecture
Doctor-derived environment/platform/DNS/queue/mail/database checks
Developer workflow command registration

When all checks pass:

LOCAL DEVELOPMENT RUNTIME
STATUS: FROZEN

When machine setup is incomplete (e.g. wildcard DNS), architecture checks may pass while DNS checks fail — run php artisan zaixos:setup-local --install first.

`php artisan zaixos:freeze-config`

Verifies the Environment & Configuration frozen layer (separate from local runtime). See FROZEN_ENGINEERING_LAYERS.md.

Doctor vs Status vs Freeze

Command	Purpose	Depth	Exit code
`zaixos:status`	What is running now	Shallow (probes only)	Always `0`
`zaixos:doctor`	Why something fails	Deep validation + fixes	`1` if FAILED
`zaixos:freeze-local`	Ready to tag runtime freeze	Architecture + machine	`1` if blocking failures

Local URLs

All local development uses *.zaixos.com — not localhost.

Surface	URL (Herd/Valet)	URL (`artisan serve`)
Company	http://zaixos.com	http://zaixos.com:8000
Identity	http://account.zaixos.com/admin/login	http://account.zaixos.com:8000/admin/login
Platform	http://platform.zaixos.com/admin	http://platform.zaixos.com:8000/admin
Clinic product	http://clinic.zaixos.com	http://clinic.zaixos.com:8000
Example tenant	http://demo.clinic.zaixos.com/admin	http://demo.clinic.zaixos.com:8000/admin
Vite HMR	http://zaixos.com:5173	http://zaixos.com:5173

Configure via .env:

env

TENANCY_BASE_DOMAIN=zaixos.com
APP_URL=http://zaixos.com
VITE_ZAIXOS_HMR_HOST=zaixos.com
SESSION_DOMAIN=.zaixos.com

With embedded artisan serve, set APP_URL=http://zaixos.com:8000.

Developer workflow

bash

# 1. One-time machine setup
php artisan zaixos:setup-local --install

# 2. Validate environment
php artisan zaixos:validate-env

# 3. Start development
composer run dev

# 4. Quick status (another terminal)
php artisan zaixos:status

# 5. Diagnose issues
php artisan zaixos:doctor

# 6. Before release / freeze verification
php artisan zaixos:freeze-config
php artisan zaixos:freeze-local

DNS setup

Wildcard tenant hosts (*.clinic.zaixos.com) require provider-specific DNS:

Provider	Setup
Herd	Base hosts via Herd; nested tenants may need `ZAIXOS_LOCAL_PROVIDER=dnsmasq`
dnsmasq	`bin/setup-zaixos-domains.sh` (invoked by provider)
Docker / DDEV / Lando	Provider-managed resolver

Run php artisan zaixos:setup-local --install — do not manually edit /etc/hosts unless the provider documentation requires it.

Boundaries (frozen)

Do not modify without architectural review:

bin/zaixos, ZaixosLocalDevelopmentOrchestrator
LocalDevelopmentProviderContract and provider registry
ZaixosLocalDoctor validator orchestration
ZaixosLocalDevelopmentFreezeVerifier
composer.json scripts.dev entry

Out of scope for this layer (separate frozen layers):

SaaS tenancy logic, Identity, Authentication, Routing
Environment & Configuration (config/*.php, env() placement)
Product features and CRM modules

Next phase

After this freeze, engineering work transitions to Product QA, End-to-End User Journey testing, and Release Validation — not infrastructure redesign.

ZAIXOS Local Development Runtime ​

Purpose ​

Quick start ​

Runtime architecture ​

Components ​

Provider abstraction ​

Official commands ​

bin/zaixos ​

composer run dev ​

php artisan zaixos:setup-local ​

php artisan zaixos:validate-env ​

php artisan zaixos:doctor ​

php artisan zaixos:status ​

php artisan zaixos:freeze-local ​

php artisan zaixos:freeze-config ​

Doctor vs Status vs Freeze ​

Local URLs ​

Developer workflow ​

DNS setup ​

Boundaries (frozen) ​

Next phase ​

ZAIXOS Local Development Runtime

Purpose

Quick start

Runtime architecture

Components

Provider abstraction

Official commands

`bin/zaixos`

`composer run dev`

`php artisan zaixos:setup-local`

`php artisan zaixos:validate-env`

`php artisan zaixos:doctor`

`php artisan zaixos:status`

`php artisan zaixos:freeze-local`

`php artisan zaixos:freeze-config`

Doctor vs Status vs Freeze

Local URLs

Developer workflow

DNS setup

Boundaries (frozen)

Next phase