> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How vly works

> The four-step loop — describe, plan, code, deploy — and what's happening at each step. The mental model to make sense of everything else.

vly turns a prompt into a deployed app through a four-step loop. The loop is the same for the first build and every iteration after.

```mermaid theme={null}
flowchart LR
    A[You describe<br/>what you want] --> B[vly plans<br/>the build]
    B --> C[An agent writes<br/>the code]
    C --> D[Auto-deploy<br/>to your URL]
    D -->|new prompt| A
    style A fill:#EDE9FE,stroke:#6D28D9,color:#0B0F1A
    style B fill:#FFFFFF,stroke:#6D28D9,color:#0B0F1A
    style C fill:#FFFFFF,stroke:#6D28D9,color:#0B0F1A
    style D fill:#CFFAFE,stroke:#06B6D4,color:#0B0F1A
```

You write the prompts. vly handles the rest.

## Step 1 — You describe

Every change starts with a prompt. The first prompt is your spec; subsequent prompts are edits. Good prompts include:

<CardGroup cols={2}>
  <Card title="What it does" icon="target">
    A user-facing description of the behavior. Not the implementation.
  </Card>

  <Card title="Who uses it" icon="users">
    Roles, permissions, who sees what. Drives the auth model.
  </Card>

  <Card title="What it stores" icon="database">
    The nouns of the app — entities and their fields. Drives the schema.
  </Card>

  <Card title="What's special" icon="sparkles">
    Anything that's not obvious. "Real-time", "needs to scale to 10k users", "must work on mobile". Drives architecture choices.
  </Card>
</CardGroup>

[Prompting fundamentals →](/prompting/fundamentals)

## Step 2 — vly plans

By default, vly enters **Plan mode** before generating any code. Planning is fast — usually 5–15 seconds — and produces a written plan with three parts:

1. **Schema** — the Convex tables and their fields, indexes, and relationships.
2. **Pages and routes** — the React Router tree, what each page shows, what data it needs.
3. **Components and features** — the shared components, the auth flow, the integrations.

You read the plan, edit it directly, or reply with a refinement. When you approve, vly proceeds to code.

<Tip>
  You can skip Plan mode for tiny edits ("change the button color to violet") by setting your default mode to [Code mode](/building/code-mode). For anything that affects multiple files or the schema, leave Plan mode on — it's the cheapest way to catch a misunderstanding.
</Tip>

[Plan mode →](/building/plan-mode)

## Step 3 — An agent writes the code

vly hands the plan off to one of three coding agents. You pick which:

<CardGroup cols={3}>
  <Card title="Claude Code" icon="brain" href="/features/agents/claude-code">
    Anthropic's Claude. Strong reasoning across many files. Default.
  </Card>

  <Card title="OpenAI Codex" icon="terminal" href="/features/agents/openai-codex">
    Fast, surgical. Best on small targeted changes.
  </Card>

  <Card title="Gemini CLI" icon="sparkles" href="/features/agents/gemini-cli">
    Strong on multi-file design and schema work.
  </Card>
</CardGroup>

The agent generates a typed React frontend, a Convex backend, and the wiring between them. Output goes into the editor as it's written — you watch live.

```mermaid theme={null}
sequenceDiagram
    participant You
    participant vly
    participant Agent
    participant Build

    You->>vly: prompt
    vly->>vly: parse + classify
    vly->>Agent: plan + workspace context
    Agent->>Agent: generate code (streaming)
    Agent->>Build: write files
    Build->>Build: type-check + bundle
    Build->>You: live preview URL
```

If type-checking fails, the agent self-corrects and retries before showing you the result. You only see the finished, building output.

## Step 4 — Auto-deploy

There's no separate deploy step. The moment a build succeeds, your preview URL updates. If you've connected a custom domain, that updates too.

vly maintains two environments by default:

* **Preview** — every change deploys here automatically. Public, but unindexed.
* **Production** — promoted on demand. Connected to your custom domain.

[Staging vs production →](/deployment/staging-vs-production)

## Behind the scenes

A typical change touches all of these layers:

```mermaid theme={null}
graph TB
    P[Prompt]
    PL[Plan]
    SC[Convex schema<br/>schema.ts]
    QM[Convex queries +<br/>mutations + actions]
    UI[React components<br/>pages + UI]
    AU[Auth + permissions]
    BL[Build + type-check]
    DP[Deploy + preview URL]

    P --> PL
    PL --> SC
    PL --> UI
    PL --> AU
    SC --> QM
    QM --> UI
    AU --> UI
    UI --> BL
    QM --> BL
    BL --> DP

    style P  fill:#EDE9FE,stroke:#6D28D9,color:#0B0F1A
    style DP fill:#CFFAFE,stroke:#06B6D4,color:#0B0F1A
```

Crucially, **types flow end-to-end**: the same `Project` type Convex returns is the type your React component consumes. There's no codegen step, no DTO mapping, no "the server returned `null` but the client expected an array" surprises.

## What you keep control of

vly does a lot for you. It does **not** lock you out of:

<AccordionGroup>
  <Accordion title="The code" icon="code">
    Every file is editable in the in-browser editor. Drop into [Code mode](/building/code-mode), make changes by hand, and the preview updates live. Your edits become part of the app's history.
  </Accordion>

  <Accordion title="The schema" icon="database">
    Convex schema files are first-class citizens. Edit them by hand or by prompt. vly handles migration when fields change. See [Convex migrations](/convex/migrations).
  </Accordion>

  <Accordion title="The design system" icon="palette">
    Tailwind config and shadcn/ui components are yours to customize. Override colors, fonts, spacing, or replace any component entirely. See [Design systems](/features/design/design-systems).
  </Accordion>

  <Accordion title="Integrations" icon="puzzle">
    Add Stripe, Resend, OpenAI, or any of [50+ integrations](/integrations/overview) by prompt or by code. vly maintains the credentials and webhook wiring; you control the business logic.
  </Accordion>

  <Accordion title="Custom domains and DNS" icon="globe">
    Bring your own domain at any tier. Apex, subdomain, multiple environments — all supported. See [Custom domains](/deployment/custom-domains).
  </Accordion>
</AccordionGroup>

## What's coming

vly's [roadmap](/resources/roadmap) tracks the major in-flight work. The biggest items:

* **Code export** — eject your project to a self-hosted Git repo. Top community ask; on the way.
* **More agent options** — additional models from Anthropic, OpenAI, Google, and others.
* **Native mobile** — initial support for React Native targets.

## Next

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="/getting-started/quickstart">
    Try the loop. Five minutes to a deployed app.
  </Card>

  <Card title="Building with vly" icon="wrench" href="/building/overview">
    The day-to-day workflow — modes, iteration, version history, collaboration.
  </Card>

  <Card title="Prompting fundamentals" icon="message-square-code" href="/prompting/fundamentals">
    The single biggest lever on output quality.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.