02 · Explore the anatomy

Before changing anything, understand the four pieces that make the app work: the manifest, the generated plugin map, the registry for custom code, and AGENTS.md. After this step you'll know where to reach for each kind of change.

app.manifest.json — the center of everything

This is the file that describes the whole app. Freshly created, an admin app looks like this:

{
  "manifestVersion": 2,
  "id": "my-store",
  "name": "my-store",
  "backend": { "provider": "mock" },
  "locale": {
    "default": "pt-BR",
    "supported": ["pt-BR", "en"],
    "currency": "BRL"
  },
  "theme": { "brand": "violet" },
  "surfaces": {
    "admin": {
      "scaffold": "admin",
      "plugins": [{ "id": "dashboard" }],
      "pages": []
    }
  }
}

Three blocks matter more than the rest:

• surfaces — each surface is one face of the app (admin, storefront, member). It declares a scaffold (the shell layout), the list of plugins and extra pages. Navigation is derived from the plugins: you turn a plugin on and its routes and menu appear — you don't write routes by hand.
• plugins — inside a surface, each entry is just { "id": "..." }. That's how you add a capability (step 04).
• backend — { "provider": "mock" } runs on sample data with zero configuration. In step 05 you switch it to "supabase".

src/plugins.generated.ts — the plugin map

// Generated by 'fayz create'. Maps manifest plugin ids → platform-bundled plugin factories.
export {}

This file connects the manifest's ids to the real plugin factories. Today it comes empty because catalog plugins are resolved by the platform bundle. Treat it as generated: you don't edit it by hand — the manifest is the source of truth.

src/registry.tsx — your code

//   import { registerBlock } from './lib/fayz-runtime'
//   registerBlock('custom:my-block', MyBlock)
export {}

This is where you register your own blocks, pages and components (levels 5–7 of the customization ladder) and then reference them from the manifest by their custom: id. While you're only configuring, it stays empty.

AGENTS.md — the manual for an agent

The scaffold includes an AGENTS.md describing the structure, the customization checklist and the Supabase walkthrough. The idea is concrete: you can open this app with an AI agent and it already knows that "customizing = editing the manifest, not writing new code", where the files live and how to connect a real database. It's documentation for the machine, versioned alongside the app.

See also: Connect your agent — how to point Claude Code, Cursor or Codex at AGENTS.md and llms.txt.

← Previous: 01 · Create the app · Next: 03 · Theme and brand →