Quickstart

This guide follows the shortest product path. You do not need to know domain-driven design or write a schema before starting.

1. Create a project

Open the modelARch workspace and create a project. Use a concrete name and a one-sentence outcome, for example:

A scheduling system where patients request appointments, staff confirm them, and each participant only sees the records they are allowed to access.

Avoid describing screens first. Start with the problem, the people involved, and the decisions the product must enforce.

2. Discover the product

Use the discovery conversation to explain:

• who uses the product and what each actor is trying to achieve;
• the central business objects and their lifecycle;
• what can go wrong or be rejected;
• who owns or can see each record;
• integrations and external constraints;
• reporting or operational questions the product must answer.

The discovery expert turns the conversation into structured model changes. Review important assumptions as they appear; a fluent answer is not the same as a confirmed decision.

3. Resolve readiness gaps

modelARch validates the model before generation. A gap is a missing decision that could produce ambiguous, insecure, or incomplete software—for example:

• an actor can reach customer-owned data without an access scope;
• a required field has no creation path;
• an event implies a cascade but its consequence is unspecified;
• a transactional system has no defined read path or an explicit decision that it needs none.

Resolve the intent rather than bypassing the gate. The validation layer exists to prevent the generator from silently inventing product behavior.

4. Design the experience

Move to Design once discovery is ready. Inspect the proposed experience blueprint:

• actor-specific surfaces;
• navigation and shell;
• views and their purpose;
• primary and contextual actions;
• transitions between views;
• visual identity and component character.

Change the authoring decisions, not generated markup. Preview and generation consume the same modeled intent.

5. Generate

Generate the project. The pipeline validates the model again, materializes a versioned representation, and produces the supported application artifacts.

A typical full-stack result includes:

• backend domain, application, infrastructure, and API layers;
• frontend routes, views, components, and API integration;
• persistence configuration and migration artifacts;
• authentication or configured add-ons;
• tests and executable contracts;
• MODEL.md and DESIGN.md as portable summaries.

Generation is not approval. Treat the result as a candidate until its checks pass.

6. Preview and deliver

Launch the generated preview and exercise the central journeys as the real actors. Verify both happy paths and rejections: permissions, invalid transitions, duplicate actions, empty states, and integration failure behavior.

When the candidate is ready, choose a delivery channel: download/export, source handoff, or managed deployment where available.

Your first revision

Return to the model and make one small product change, such as adding a cancellation reason or restricting an action to staff. Generate again and inspect the delta. That second generation—not the first—is the fastest way to understand the modelARch contract.

Next, read Projects and revisions and the Regenerative lifecycle.