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

  1. 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.

  2. 02

    Explicit override surfaces

    Consumers override named components and styles, not arbitrary files. Override points are declared by the theme and stable across versions.

  3. 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.

  4. 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.