Portaljs Architect

PortalJS — Architect

Overview

The advisory entry point for a PortalJS project. Before anything gets scaffolded, this

skill works out what to build: given the kind of portal, the shape of the data, and its

purpose, it fills six architecture slots (storage, catalog, compute, access, hosting,

metadata), resolves two build-time knobs (per-dataset data tier and the portal-wide

DATA_QUERY mode), and hands off to the concrete build skills. It decides; it does not

build. When the brief is thin it interviews in short rounds and never dead-ends — every

question has a sensible default, reachable by replying "use defaults."

Prerequisites

• A rough idea of the portal's purpose and data (exact numbers are not required — the

interview supplies defaults for anything missing).

• Optional: local files or a directory of sample data to inspect for size and shape.
• No PortalJS project needs to exist yet; this skill runs before scaffolding.

Instructions

The canonical, full step-by-step workflow lives in

.claude/commands/portaljs-architect.md —

that file is the single source of truth. Follow it when executing this skill:

• Parse $ARGUMENTS for anything already specified, then interview for what's

missing, one round at a time: (1) what's being built, (2) what the data is,

(3) what it's for, (4) constraints. Accept "use defaults" at any point. Inspect

named files/directories with du -sh and line counts to ground size guesses.

• Derive the recommendation by matching the answers against the decision tables —

Storage/Catalog/Compute by data volume and query needs, Access/Hosting by public

vs. private, Metadata by standards-compliance needs — then resolve the two

build-time knobs: per-dataset data tier (inline | LFS | external) and the

portal-wide DATA_QUERY mode (flat | duckdb).

• Echo the architecture brief (stack, reasoning per slot, deviations from default,

deferred items) and wait for confirmation ("go") or corrections.

• On confirmation, persist the brief to ./ARCHITECTURE.md in the working directory.
• Hand off to the build skills — /portaljs-new-portal, /portaljs-add-dataset,

/portaljs-connect-ckan, /portaljs-define-schema, /portaljs-deploy — mapped

from the brief, and offer to run the first one.

Output

• Created: ./ARCHITECTURE.md documenting the six slots, the two build-time

knobs, the reasoning, and anything deferred to a later build step.

• Modified: nothing else — this skill is advisory only.
• Verified: the brief was echoed back and confirmed before being persisted.
• Result: a concrete, named sequence of follow-up skill invocations

(e.g. /portaljs-new-portal → /portaljs-add-dataset → /portaljs-deploy).

Error Handling

| Symptom | Cause | Fix |

| --- | --- | --- |

| Skill keeps asking rounds of questions | Brief was thin or $ARGUMENTS omitted | Answer inline, or reply "use defaults" to accept the opinionated default stack |

| Recommendation looks generic | Rounds were skipped without real data details | Give actual size/shape/cadence, or point at files for du -sh inspection |

| ARCHITECTURE.md never appears | Confirmation step was skipped | Reply "go" once the echoed brief looks right |

| Scaffolded portal has the wrong DATA_QUERY | Flat downgrade wasn't applied | Run the perl -pi -e one-liner from the command file against lib/datasets.ts |

| Hand-off names a skill that doesn't exist | Decision maps to a *(planned)* skill (e.g. /connect-openmetadata) | Treat it as designed-in/built-later; proceed with the closest available skill |

Examples

Example 1 — National statistics office, DCAT-AP harvesting

/portaljs-architect We're a national statistics office. ~200 datasets, mostly large
CSVs (some GBs), updated quarterly, all public, and we must publish DCAT-AP for the
EU data portal.

Infers a multi-publisher, analytics-grade portal. Recommends Parquet on R2 + DuckLake +

DuckDB, static Cloudflare Pages, Frictionless + DCAT-AP metadata, owner namespace,

data tier external for the Parquet, DATA_QUERY=duckdb. Writes ARCHITECTURE.md and

hands off to /portaljs-new-portal then /portaljs-add-dataset.

Example 2 — Small nonprofit, no arguments given

/portaljs-architect

Runs the full four-round interview since nothing was pre-filled. Accepting defaults at

each round lands on the opinionated default stack: repo files or Git-LFS + R2 storage,

datasets.json catalog, DuckDB compute, static access on Cloudflare Pages, Frictionless

metadata, theme namespace, data tier LFS, DATA_QUERY=duckdb.

Example 3 — Internal catalog with restricted datasets

/portaljs-architect Internal engineering data catalog, single team, dozens of CSVs,
some of it access-controlled to specific roles.

The private-data answer in Round 2 flips Access/Hosting to runtime + backend RBAC on

Cloudflare Workers — flagged as the larger, opt-in build — while Storage/Catalog/Compute

still follow the volume-based defaults.

Resources

• Full workflow: .claude/commands/portaljs-architect.md
• Reference: references/reference.md
• Decision framework: site/content/docs/architecture/decision-framework.md
• Related skills: /portaljs-new-portal, /portaljs-add-dataset, /portaljs-connect-ckan, /portaljs-define-schema, /portaljs-deploy