Architecture decision framework

PortalJS doesn't just build a portal; it helps you decide what to build. This is the advisory layer: a small set of questions that map your needs onto a concrete architecture the build skills can then scaffold. It is opinionated by default and explicit about when to deviate.

Three questions

Every recommendation comes from three questions:

1. What are you building? An open-data portal, an internal data catalog, a project/research data site, a public-sector portal with harvesting obligations…
2. What is your data? Size, shape (tabular / geospatial / documents), update frequency, number of datasets, sensitivity.
3. What is it for? Publishing/discovery, analytics/querying, redistribution, compliance, machine-to-machine harvesting.

Decision axes

The answers resolve into a handful of axes. Each pushes the recommendation along the storage + compute spectrum.

The recommendation

Each axis-set resolves into a stack across five slots:

Opinionated defaults

When in doubt, PortalJS recommends the open, cheap, composable path:

• git + giftless/R2 + Parquet + DuckLake + DuckDB, static on Cloudflare Pages, Frictionless metadata.
• Storage stays S3-compatible, so R2 is the default but never a lock-in.
• DuckDB is the query engine everywhere — client-side (Wasm) until data size or privacy forces a server (Cloudflare Workers).

When to deviate

• Role-based private data, multi-team governance → a backend that owns RBAC (CKAN or OpenMetadata) + the runtime mode. The portal surfaces it.
• Existing warehouse / SQL-native team → keep the warehouse as the datastore; the data-query contract has a datastore implementation.
• Tiny, static, a handful of CSVs → don't reach for the lakehouse; flat files + client-side preview is the whole stack.

The /architect skill (design)

A new advisory skill that runs the framework as an interview and emits an architecture brief, then hands off to the build skills.

Interview (rounds, skippable with sensible defaults):

1. Building — what kind of portal, and who runs it.
2. Data — volume, shape, update cadence, dataset count, sensitivity.
3. Use — publish/discover, analytics, redistribution, compliance/harvest.
4. Constraints — team size/skills, budget, cloud preference, existing backends.

Output — an architecture brief: the five-slot recommendation above, the reasoning per axis, and the deviations chosen. Echoed for confirmation.

Handoff: the brief parameterizes the build skills — /new-portal (surfaces + namespace mode), the storage/compute choice (Git-LFS+R2 / lakehouse / datastore), the metadata profile (/define-schema), and any backend wiring (/connect-ckan, /connect-openmetadata). The advisory layer decides; the build layer executes.