# Choosing an App Pattern

Start with the smallest blessed template that matches the delivery shape; copy
it, then change the manifest and source. Run local validation from the
repository root: `node scripts/artifacts/validate-local --dir <appDir>`.

| Situation | Start from | Data approach |
| --- | --- | --- |
| Landing page, simple website, or app without runtime data | `artifact-draft` | No dataset until one is actually needed. |
| Chart-heavy dashboard | `react-dashboard` | Add declared live datasets as needed. |
| Dashboard with joins, derived metrics, or multiple read-only relations | `multi-source-dashboard` | Bounded live SQL datasets; prototype with catalog tools and `run_psql`. |
| Private operational action surface | `internal-tool` | Keep private UI and any server work scoped to declared artifact routes. |
| Private API-first tool | `python-api` | Declare `/_artifact/api/*`; keep viewer auth and external calls server-side. |
| Website or app with its own backend API (two parts, possibly two languages) | `web-and-api` | One artifact with `parts`: a static website part and a server API part, routed by path under one address. |
| MCP server exposed to Topline chat or Topline Coding Agent tasks | `fastmcp-server` | Exact FastMCP 3.4.7 lock, stateless JSON Streamable HTTP at `/_artifact/mcp`; connect and review after live promotion in Developer Access. |
| External webhook receiver | Platform service | Current artifact routing does not expose provider-verifiable machine ingress. |
| Customer API that must be synced on a schedule | Data Sources build, then its data pipeline artifact | Create a source, connection, connector runtime contract, materialized catalog resources, and a pipeline; with the workspace on it becomes a data pipeline artifact. Build an artifact app only as a downstream consumer. |
| Change which tables a connector syncs or when | Data pipeline artifact | Edit the `pipelineManifest` as a draft; a person publishes. See `examples/data-pipeline-artifact/EXAMPLE.md`. |
| Exact narrow count aggregate | `live-aggregate-dashboard` | `service_aggregate` binding with `aggregate.type: "count"` only. |
| A customer viewing only their own customer row | `viewer-scoped-dashboard` | Viewer binding with required session and `customers.email` filter. |

## One app, several parts

One app is always one artifact, even when it has a website and a separate
backend, or code in two languages. Declare `parts` in the manifest:

- A `static` part serves built files (`build.outputDir`) straight from storage.
  Set `spa: true` to send `index.html` for page navigations that match no file.
- A `server` part runs its own `entryPoint` (`language` node or python) on its
  own machine size (`resources` on the part, starting from the top-level ones).
- Each part's `build.command` runs in its own `dir`; the top-level `build` is
  optional and runs first, at the app root.
- Routes pick the part with `part`. Paths are exact or end in `/*`; the longest
  match wins, and unmatched paths go to the first static part. Platform routes
  (`/_artifact/data/*`, `/_artifact/knowledge/*`) are always served by Topline.
- Use relative asset URLs (`./app.js`) and hash routes (`#/reports`) so the
  same files work on the draft, live, and version addresses.

Up to four parts; at least one must be a server part. `mcp_server` apps stay
single-part.

## Data-pattern decision

Use a **live SQL dataset** for ordinary interactive reporting, joins, ratios,
averages, time series, and metrics that must reflect the source within the
declared TTL. It is the default for private dashboards.

Use a **source binding** only for its two narrow supported cases: viewer-scoped
customer rows or a count aggregate. Do not force a multi-table metric through a
binding.

Use a **precomputed dataset** when a report is dense or its bounded query is too
expensive for a request. It still exposes the same declared data route, but
reads platform-managed private JSON after warming. Declare `warmParams` for all
parameter variants that must be ready.

Use an **upstream materialized table or view** when the source-side preparation
itself needs a durable data product, shared reuse, or a cadence independent of
one app. This is artifact-adjacent/platform data work: make it available and
understood through the approved catalog/read-only path first, then have the app
query it as a bounded live dataset. Do not create or manage upstream
materialization from artifact runtime code.

Use a **Data Sources connector pipeline** when the customer is introducing a
new API or system that must be ingested repeatedly. The conversation drives the
build; the Data Source owns the connection, secrets, checkpoints and rows, and
with the Data Sources workspace on its data pipeline artifact owns which tables
sync on which schedule. Start with
`examples/customer-api-source-pipeline/EXAMPLE.md`, then
`examples/data-pipeline-artifact/EXAMPLE.md`.

## UI contract

For a live view, show the user an explicit last-updated/freshness state and
poll only at a cadence consistent with the TTL. Model empty, unavailable,
partial, stale, and error states; a local handler may return an empty response
or a clear error, never template/sample tenant rows that disguise a failed live
route.

Keep the package reproducible. The trusted builder provides the ordinary React
dashboard toolchain; do not commit or rely on `node_modules` in the app package.