Consumer-local route · src/pages-local/vision.astro
Vision
Portfolio Engine is an open-source backbone for personal and professional websites. The goal is a shared commons of Astro/Tailwind capabilities that downstream sites depend on — not a one-off generator that disappears once your site is shipped.
Site owners contribute needs. AI coding agents implement scoped issues against typed contracts. Humans review the shared foundation. The engine is the artifact every contributor is improving at the same time.
This demo is the project's own showcase — Apache-2.0 licensed, built from the same @portfolio-engine/* packages a downstream site would install. It is intentionally not a generated personal website. If you are here to evaluate the engine, read the cards below and follow the workflow guide.
Design principles
Choices made on purpose
- 01
Open-source commons
Every good contribution improves the backbone for everyone. Capabilities that are obviously reusable belong in the engine, not in private one-off forks.
- 02
Explicit override surfaces
Consumers override named components and styles, not arbitrary files. Override points are declared by the theme and stable across versions.
- 03
Two-repo model
Engine packages live in a public repo. Your content, config, and identity live in a private repo. They share no git history and no secrets.
- 04
Strict layering
schema → engine-core → editorial-theme → consumer. Dependencies only point downward. Banned: astro-theme-provider, astro-pages, astro-public.
Working principles
How that plays out, day to day
-
Config is JSON, validated by Zod
site.json, navigation.json, theme.json, features.json — four files, one schema package, friendly errors at build time.
-
Content is plain Astro collections
Profile, projects, writing use Astro's native content layer. The engine never touches your markdown.
-
Agent-safe workflow
Scoped GitHub issues, label taxonomy, AGENTS.md, Copilot instructions, and visual QA loops make AI-assisted implementation reviewable instead of opaque.
-
Three route-ownership modes
Theme-injected routes, consumer-local routes via a registry JSON, and ordinary src/pages — pick the right mode per page.
-
No packaged public/ in the engine
Engine packages ship code, not assets. Your public/ directory stays yours. CI enforces this rule on every commit.