# The two paths

There are two ways to build with the Fayz SDK, and picking the right one up front saves rework. Either you use the **Fayz App** — a complete admin shell assembled from your config — or you go **Fayz Headless**, consuming the core and the plugin bundles directly in your own project. Both use the same plugins and the same backend; what changes is **who owns the shell** around the plugins.

Rule of thumb: if the product **is** the management app (a multi-tenant SaaS, an admin), go with the Fayz App. If you already have your own site — a landing page, a store with a strong brand — and you just want to plug a few capabilities into it, go Headless.

## Fayz App

You declare the app config — in `app.manifest.json` or in code with `defineSaas` — turn on a set of plugins, and get a finished app: admin shell, navigation generated from the plugins, tenant switching, permissions and CRUD screens. It's the fastest path to a complete multi-tenant product, and it's what `fayz create admin` generates for you.

```ts
import { defineSaas } from '@fayz-ai/saas'
import { createAgendaPlugin } from '@fayz-ai/plugin-agenda'
import { createCrmPlugin } from '@fayz-ai/plugin-crm'

export default defineSaas({
  name: 'My Clinic',
  plugins: [createAgendaPlugin(), createCrmPlugin()],
})
// → complete admin shell: navigation, tenants, permissions, CRUD
```

You get in through the [Quickstart](/en/docs/quickstart), which generates exactly this kind of app and boots it in mock mode. When consuming the packages in code, mock providers start out empty — [Mock and sample data](/en/docs/apps/mock-and-sample-data) shows how to seed them.

## Fayz Headless {% badge status="beta" %}

You import `@fayz-ai/core` and assemble the surfaces yourself, injecting the plugin bundles (`{ manifest, Provider }`) and serving their subpaths under `/public`. It's the path for a bespoke site — marketing, store, portal — that only wants a few Fayz capabilities without adopting the whole shell. The theme inherits from your own tokens, so the plugin looks like your site, not like the default admin.

{% callout type="warn" %}
The Headless path is real and in use, but it has **less documentation** than the Fayz App today. Expect to lean more on reading the types and the examples, and less on step-by-step guides, while it matures.
{% /callout %}

## Comparison

| | **Fayz App** | **Fayz Headless** |
|---|---|---|
| Who builds the shell | the SDK (ready to go) | you, in your project |
| Navigation / routes | generated from the manifest | you wire up your own |
| Multi-tenancy + permissions | included | you integrate what you need |
| Theme | Fayz shell and tokens | inherits from your own tokens |
| Starting point | `fayz create admin` | a site you already have |
| Best for | SaaS / management admin | branded site + a few capabilities |
| Cost of entry | minimal — running in minutes | higher — you own the integration |
| Documentation today | complete | maturing |

What you gain with the Fayz App — shell, navigation, tenancy — is exactly what you give up control over. Headless inverts that: you control everything, and you pay for it by building the integration. Neither is "better"; it depends on whether the product is the management app or a site that consumes capabilities.

## Pick yours

{% cards %}
{% card title="Path A · Fayz App" href="/en/docs/quickstart" icon="🏗️" %}
Start with the Quickstart: a complete admin shell running in minutes.
{% /card %}
{% card title="Path B · Headless" href="/en/docs/apps/headless" icon="🧱" %}
Core + plugin bundles inside your own site.
{% /card %}
{% /cards %}