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
1---2name: portaljs-architect3description: Recommend a data-portal architecture (storage, compute, catalog, access, hosting, metadata) from stated needs, then hand off to the build skills. The advisory entry point. Use when starting a new data-portal project and the underlying architecture has not yet been decided.4license: MIT5---6
7# PortalJS — Architect
8
9## Overview
10The advisory entry point for a PortalJS project. Before anything gets scaffolded, this
11skill works out what to build: given the kind of portal, the shape of the data, and its
12purpose, it fills six architecture slots (storage, catalog, compute, access, hosting,
13metadata), resolves two build-time knobs (per-dataset data tier and the portal-wide
14`DATA_QUERY` mode), and hands off to the concrete build skills. It decides; it does not
15build. When the brief is thin it interviews in short rounds and never dead-ends — every
16question has a sensible default, reachable by replying "use defaults."
17
18## Prerequisites
19- A rough idea of the portal's purpose and data (exact numbers are not required — the
20 interview supplies defaults for anything missing).
21- Optional: local files or a directory of sample data to inspect for size and shape.
22- No PortalJS project needs to exist yet; this skill runs before scaffolding.
23
24## Instructions
25The canonical, full step-by-step workflow lives in
26[`.claude/commands/portaljs-architect.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-architect.md) —
27that file is the single source of truth. Follow it when executing this skill:
28
291. Parse `$ARGUMENTS` for anything already specified, then interview for what's
30 missing, one round at a time: (1) what's being built, (2) what the data is,
31 (3) what it's for, (4) constraints. Accept "use defaults" at any point. Inspect
32 named files/directories with `du -sh` and line counts to ground size guesses.
332. Derive the recommendation by matching the answers against the decision tables —
34 Storage/Catalog/Compute by data volume and query needs, Access/Hosting by public
35 vs. private, Metadata by standards-compliance needs — then resolve the two
36 build-time knobs: per-dataset **data tier** (`inline | LFS | external`) and the
37 portal-wide **`DATA_QUERY`** mode (`flat | duckdb`).
383. Echo the architecture brief (stack, reasoning per slot, deviations from default,
39 deferred items) and wait for confirmation ("go") or corrections.
404. On confirmation, persist the brief to `./ARCHITECTURE.md` in the working directory.
415. Hand off to the build skills — `/portaljs-new-portal`, `/portaljs-add-dataset`,
42 `/portaljs-connect-ckan`, `/portaljs-define-schema`, `/portaljs-deploy` — mapped
43 from the brief, and offer to run the first one.
44
45## Output
46- **Created:** `./ARCHITECTURE.md` documenting the six slots, the two build-time
47 knobs, the reasoning, and anything deferred to a later build step.
48- **Modified:** nothing else — this skill is advisory only.
49- **Verified:** the brief was echoed back and confirmed before being persisted.
50- **Result:** a concrete, named sequence of follow-up skill invocations
51 (e.g. `/portaljs-new-portal` → `/portaljs-add-dataset` → `/portaljs-deploy`).
52
53## Error Handling
54| Symptom | Cause | Fix |
55| --- | --- | --- |
56| Skill keeps asking rounds of questions | Brief was thin or `$ARGUMENTS` omitted | Answer inline, or reply "use defaults" to accept the opinionated default stack |
57| Recommendation looks generic | Rounds were skipped without real data details | Give actual size/shape/cadence, or point at files for `du -sh` inspection |
58| `ARCHITECTURE.md` never appears | Confirmation step was skipped | Reply "go" once the echoed brief looks right |
59| 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` |
60| 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 |
61
62## Examples
63### Example 1 — National statistics office, DCAT-AP harvesting
64```
65/portaljs-architect We're a national statistics office. ~200 datasets, mostly large
66CSVs (some GBs), updated quarterly, all public, and we must publish DCAT-AP for the
67EU data portal.
68```
69Infers a multi-publisher, analytics-grade portal. Recommends Parquet on R2 + DuckLake +
70DuckDB, static Cloudflare Pages, Frictionless + DCAT-AP metadata, `owner` namespace,
71data tier `external` for the Parquet, `DATA_QUERY=duckdb`. Writes `ARCHITECTURE.md` and
72hands off to `/portaljs-new-portal` then `/portaljs-add-dataset`.
73
74### Example 2 — Small nonprofit, no arguments given
75```
76/portaljs-architect
77```
78Runs the full four-round interview since nothing was pre-filled. Accepting defaults at
79each round lands on the opinionated default stack: repo files or Git-LFS + R2 storage,
80`datasets.json` catalog, DuckDB compute, static access on Cloudflare Pages, Frictionless
81metadata, `theme` namespace, data tier LFS, `DATA_QUERY=duckdb`.
82
83### Example 3 — Internal catalog with restricted datasets
84```
85/portaljs-architect Internal engineering data catalog, single team, dozens of CSVs,
86some of it access-controlled to specific roles.
87```
88The private-data answer in Round 2 flips Access/Hosting to runtime + backend RBAC on
89Cloudflare Workers — flagged as the larger, opt-in build — while Storage/Catalog/Compute
90still follow the volume-based defaults.
91
92## Resources
93- Full workflow: [`.claude/commands/portaljs-architect.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-architect.md)
94- Reference: [`references/reference.md`](references/reference.md)
95- Decision framework: [`site/content/docs/architecture/decision-framework.md`](https://github.com/datopian/portaljs/blob/main/site/content/docs/architecture/decision-framework.md)
96- Related skills: `/portaljs-new-portal`, `/portaljs-add-dataset`, `/portaljs-connect-ckan`, `/portaljs-define-schema`, `/portaljs-deploy`
datopian