ConceptsSurfaces

What is a Surface?

A surface is one page inside an app, and the unit the platform API addresses. It is the render of a Receipt: reproducible, versioned, and capability-bound from the moment it ships.

Start with What is an App? if you have not read it. An app is what a customer gets — its pages together with the records they write, the sign-in its visitors use and the appearance that ties them together. A surface is one of those pages. Composing a surface is not the same as shipping an app; publishing, addresses and exports belong to the app, not to the page.

Page vs Surface

Pages are documents you author once and update by hand. Surfaces are the materialised form of a Receipt — a line-numbered recipe of blocks, properties, capabilities and theme that PhiCo proposes and you accept before publish.

PageSurface
Static documentReceipt-materialised render
Hand-authored contentComposable from a typed catalog
One-shot renderReproducible from the same Receipt
No audit trailDiffable revision history

What a surface carries

  • Identity — an ID that stays stable as the surface changes.
  • Metadata — title, slug, description and preview image.
  • Blocks — the tree of typed pieces that renders.
  • Capabilities — the powers it declared, and their configuration.
  • Revisions — every accepted Receipt, kept as a snapshot.

How surfaces change

Every change is a new Receipt, and nothing publishes until a human accepts the diff.

  • Add capabilities — any of the canonical four: platform/persistence, platform/entities, platform/navigation, platform/interaction. Their configuration goes into the Receipt.
  • Revision history — every accepted Receipt is a snapshot; roll back to a previous one, or diff two of them line by line. How far back the history reaches depends on your plan.
  • Responsive layout — block layouts declare xs/sm/md/lg breakpoints, and the runtime renders the right one per device.

Surfaces connect

  • Link — navigate to the other surfaces of the same app.
  • Share — travel with their app when it is published, exported or listed on the marketplace.
  • Inherit — start from a starter and change it.

Going live is an app-level act: an app claims one public address and every one of its surfaces is served under it. See Publishing your app.

Surface composition

Surfaces are composed from blocks:

Surface
├── Block (container)
│   ├── Block (heading)
│   ├── Block (text)
│   └── Block (button)
├── Block (grid)
│   ├── Block (image)
│   └── Block (image)
└── Capabilities
    ├── persistence
    ├── interaction
    └── navigation

Learn more about blocks and the composition model.

Next

AppsBlocks