System Design

Built with @tech0ver/starlight, the shared Astro/Starlight UI for tech0ver sites.

Run locally

Use Node.js 24 and Bun 1.4.0.

The shared package is installed from GitHub Packages through the committed .npmrc. Set GITHUB_PACKAGES_READ_TOKEN to a GitHub personal access token (classic) with read:packages and access to @tech0ver/starlight. Authentication is required even for public packages. Keep the token outside the repository and export it in your shell before installing dependencies.

bun install
bun run dev      # dev server at http://localhost:4321/sysdes/
bun run build    # production build into dist/
bun run preview  # serve dist/ locally

Search requires the Pagefind index generated by bun run build; use the production preview to check search results.

Shared UI updates

After a successful package publication, Starlight sends a starlight-release event to this repository. Update shared Starlight calls the shared updater from the Starlight main branch. It opens a PR with the package version, required peer dependency versions, and bun.lock. Run the same workflow manually from main with a published version to retry an update. Repeated events do not create duplicate PRs or downgrade the dependency. Review release notes and any migration before approving; updates do not merge automatically.

The receiver must be on the default branch. Configure Actions secrets UPDATE_APP_ID and UPDATE_APP_PRIVATE_KEY for the update GitHub App, installed on this repository with Contents: Read and write and Pull requests: Read and write permissions. Organization secrets can be shared with selected repositories. See the Starlight rollout instructions for publisher setup and enabling delivery after the receiver is ready.

To update manually, change @tech0ver/starlight in package.json and bun.lock using the peer dependency versions documented by that release, then rebuild. Site settings are in astro.config.mjs; articles, glossary entries, diagrams, and site extensions stay in this repository. Shared visual changes belong in the package.

Pull requests run a frozen install, production build, and Chromium checks on desktop and mobile in light and dark themes. The checks cover the home page, articles, glossary, Markdown exports, search, theme persistence, navigation, and browser errors. Run them against a fresh production build locally:

bunx --no-install playwright install --with-deps chromium
bun run build
bun run test:browser

Failed CI runs upload a browser report with screenshots and traces. GitHub Actions uses GITHUB_TOKEN with packages: read; this repository must have read access under the package's Manage Actions access settings. Pushes to main build and deploy to GitHub Pages.