Consumer-local route · src/pages-local/architecture.astro

Architecture

portfolio-engine is split into four packages, each one a strict downward dependency. The interactive diagram below renders the layers and their direct dependencies — click a layer to see what it does and what it depends on.

Layers, interactive

This diagram is a self-contained HTML file under public/assets/demos/architecture/, embedded via the theme's IframeEmbed component. Same-origin so the host allowlist does not apply; sandboxed to allow-scripts only, no cookies or storage shared.

Same-origin static demo, rendered through the theme's typed IframeEmbed wrapper. The component rejects http://, javascript:, data:, protocol-relative, and control-character src values at build time.

The layers, in words

Layer 01

@portfolio-engine/schema

Pure Zod schemas. No Astro, no Vite, no framework dependency. The canonical shape of every config file, content entry, and registry record. Ships as a leaf package so every other layer can depend on it cleanly.

Layer 02

@portfolio-engine/engine-core

The Astro integration. Loads JSON config, validates against the schema package, exposes virtual modules (@portfolio-engine:config, :context, :routes, :overrides), discovers routes, and writes .portfolio-engine/manifest.json on build. Consumers never import this directly.

Layer 03

@portfolio-engine/editorial-theme

The first-party theme. Owns layouts, components, the global stylesheet, and the five named override surfaces. Exports editorialTheme() — the single Astro integration that wraps engine-core and configures Tailwind v4 via PostCSS.

Layer 04

Your consumer site

Private repo. Holds src/config/*.json, src/content/**, src/overrides/, and optionally src/pages-local/ + src/registry/. Depends on the editorial theme via the published npm package. Never on engine-core or schema directly.

For the live route registry and override-surface contract — read directly from @portfolio-engine/editorial-theme at build time — see the feature matrix .