Choose how to adopt Pulsar

Adopt Pulsar through one of two paths: build the verified first feature in a new Laravel application, or preserve an existing application's behavior while adding one bounded slice. Both paths end at the same tested Pulsar structure.

Choose your path

New application. Check the prerequisites, choose a small first slice, and take either the concise Quickstart or the complete Installation, first Service, bootstrap wiring, first feature, and project-tour journey. A greenfield application does not need an inventory of legacy behavior or an application rollback checkpoint before its first commit.

Existing application. Decide whether the boundary fits the team, protect current behavior with a regression test, and establish a reversible checkpoint before changing Composer state. Then adopt Pulsar in the application by adding one slice beside the old code. Existing routes and stock Laravel classes do not move merely because new code uses Pulsar.

Both paths use project-local vendor/bin/pulsar, the current published package, and the same final app/Pulsar structure. The difference is the evidence required before and after each mutation.

Confirm that the team is ready

Adoption is ready to start only when all six statements are true:

• PHP, Laravel, and Composer meet the published prerequisites, and Composer runs from the application root.
• The team agrees that app/Pulsar is a strict architectural boundary, not another name for all of app/.
• The Service audience and Domain capability names can be chosen together and enforced in review.
• One small behavior has a passing public-boundary regression test, or can receive one before adoption.
• The application has a clean version-control checkpoint and a reviewed database backup and reversal plan.
• The first slice can be observed and rolled back without unrelated architecture work.

Stop when Pulsar is a poor current fit

Stop and reassess if the application is small enough that the team deliberately prefers stock Laravel flexibility, or if the team has not agreed to enforce the boundary. A generator cannot replace architectural review.

Also stop when the proposal is a big-bang rewrite, requires moving all existing app/ code, or spans several audiences and Domains. Do not proceed with an unsupported runtime, a package selection outside the current gate, or a v0.3 application that has not completed its package-specific upgrade. Existing failures with no trustworthy baseline or rollback point make adoption unsafe.

A customized bootstrap that Pulsar cannot patch safely is a review boundary. So is a first slice that requires unbounded shared-schema conversion, ambiguous Model moves, or volatile integrations without a compatibility seam. These conditions call for a smaller design or different timing, not a forced install.

Select the first Pulsar slice

Every row must pass. Reject or reduce the slice as soon as one row fails.

Test	Pass condition	Reject or reduce the slice when
Audience	One existing or new audience owns the entry point.	Several audiences need the same first change.
Capability	One Domain capability describes the behavior.	The name is a technical layer or spans unrelated business capabilities.
Public boundary	One route, command, or listener has observable input and output.	Success depends only on internal class construction.
Legacy seam	Existing behavior has a regression test and remains callable throughout.	The first step must delete or rename the old path.
Data	The slice owns new schema or has one explicit compatibility seam.	It requires destructive shared-table conversion or an ambiguous Model move.
Dependencies	Volatile outbound work is absent or already protected by a Contract and Adapter seam.	Authentication, tenancy, queues, and third-party writes all arrive together.
Reversal	Code and schema can return to the checkpoint with a reviewed plan.	Recovery relies on guessing a migration batch or deleting app/Pulsar.

The documented Orders API passes this rubric. One Client audience owns the HTTP entry point, Orders is one business capability, and POST /api/client/orders has observable input and response behavior. It adds its own table and avoids outbound integrations. In an existing application it remains beside the representative named legacy Orders route rather than replacing it.

This is a selection method, not a mandate to begin with Orders. Prefer a behavior that the team can name, test at its public boundary, deploy independently, and reverse deliberately.

Keep old and new code in deliberate homes

Pulsar is additive. Existing Controllers, Form Requests, Models, routes, providers, configuration, migrations, factories, seeders, and tests keep their stock Laravel homes while they continue to own legacy behavior. New Pulsar architecture lives under app/Pulsar; new Laravel migrations and tests stay in their stock directories.

Move an existing type only when that exact type must participate in a Pulsar dependency edge and its callers can migrate with parity evidence. Never move an entire parent directory as a prerequisite. The existing-application walkthrough provides the complete placement table and the legacy/new route contrast.

Use the current version gate

These pages cover the published Pulsar v0.4.1 package. Before running the installer, confirm that composer.json contains ^0.4.1 in require-dev and composer.lock selects v0.4.1 at source and distribution reference fc14af65381c9bcd7fc99b05f893cef0344dad54.

Stop on any different selection or unexplained reference. If the application uses v0.3, complete the package's version-specific upgrade first; Operation methods and wiring changed across that boundary. This onboarding page does not reproduce a partial upgrade recipe or claim that an unpublished site route already owns it.

Continue with a complete path

For a new application:

1. Confirm the prerequisites and choose a slice that passes the rubric.
2. Use Quickstart, or follow Installation through Build your first Pulsar feature for the fully explained path.
3. Finish with the project tour and review the resulting dependency direction before expanding the slice.

For an existing application:

1. Record passing legacy behavior, collision inventory, a clean commit, and a reviewed data-reversal plan.
2. Follow Adopt Pulsar in an existing application through its four checkpoints; stop on drift or unsafe mutation.
3. Commit only after both the unchanged legacy behavior and the new public-boundary feature tests pass.