site-foundation
The base of sahin.io/angel-investments — the stack, the route manifest, the two render paths (static renderers vs React pages), the static build, and the order in which the page skills rebuild the site. Use first when rebuilding the site from scratch, before adding a new route family, or when orienting in how a URL becomes an HTML file.
- Source file
.claude/skills/site-foundation/SKILL.md
Site foundation
What it is
A public, statically generated portfolio site served at https://sahin.io/angel-investments/
(Cloudflare Pages behind the sahin.io proxy; see production-deployment). Every public URL is a
route in one manifest; every route is pre-rendered to HTML at build time by Astro; only the
chrome's theme switcher and search, the hub app and React pages with state hydrate as islands,
not the whole page. Static pages ship no JavaScript. (It used to be hydrated by a
React client bundle.
Stack (package.json): Astro 7 (static output, React islands), React 19, Tailwind 4, TypeScript 5.9,
vitest, tsx. Copy lives in YAML/Markdown under content/ (see page-content-yaml).
Files
server/seoRouteManifest.ts—createSeoRouteManifest()builds every route ({ path, canonicalUrl, file, kind, title, lastModified, indexing });renderRouteDocument()dispatches by kind to the static renderers;renderRouteHtml()wraps it and refuses anoindexroute whose HTML lacks the robots meta.server/publicPortfolio.ts—RouteKindunion: home, explore, legacyFeature, reactPage, newsDetail, company, category, subcategory, companyInvestors, categoryInvestors, subcategoryInvestors, investorsIndex, coInvestor, guidesIndex, guide, about, thesis, pitch, faq, glossary, list, cityList, listsIndex.server/reactPageRoutes.ts— React-only routes:SINGLE_PAGESand slugFAMILIES(/founder,/status,/news,/sectors,/market); listed in the manifest asreactPage.server/publicReactPages.ts—reactPageForRoute(path, ctx)returns{ kind, props }for any route that has a React page (SINGLE_PAGES/FAMILIES first, then route kinds and exact paths).server/publicPages/*.ts— one props builder per React page (build<Name>Props,<name>PageMeta).client/src/publicPages/—*Page.tsx,*Types.ts,types.ts(PublicReactPageunion),PublicReactPageView.tsx(PageBody),components.server.ts,styles/*.css.server/publicReactDocument.ts—renderPublicReactDocument()merges static head + React body.astro/pages/ssr/[...file].astro— every non-hub route;astro/pages/index.astro— the hub;astro/layouts/Document.astro(the document shell),astro/components/Chrome.astro(the React chrome rendered at build time +astro/scripts/chrome.ts),astro/islands/*(search island).server/staticBuild.ts—loadStaticBuild()(data, manifest, context once per build),renderStaticRoute(),writeBuildOutputs(),copyPublicAssets();scripts/astro-postbuild.tsruns them afterastro build.- There is no client entry or SPA any more:
pnpm dev(the Express server for tRPC/auth) serves public pages from the lastpnpm build:cloudflareoutput; preview the static build withastro-static/wrangler pages dev dist/cloudflare.
Two render paths
- Static renderer.
renderRouteDocument()→renderPublic*Page/renderEditorialDocument/renderListRoute/renderLegacyFeaturePage/renderReactShellPage, each ending inrenderDocument(ctx, headSpec(...), breadcrumbs, body). This HTML always exists: it owns the<head>(title, canonical, OG, JSON-LD — seeseo-head-and-schema) and the crawlable body. - React page. If
reactPageForRoute()returns a page,renderPublicReactDocument()keeps the static head, replaces the static header with the server-rendered React layout (App→NavBar+PublicReactPageView), and passes the static breadcrumb and footer in asServerChrome { crumbHtml, footerHtml, articleHtml? }. Kinds inEMBED_SERVER_BODY_KINDS(companyView,companyInvestorsView,categoryInvestorsView,firmView) also keep the static body below the React part; editorial routes keep their<article class="editorial">. With no React page, the static body is wrapped inServerPageBody(.public-page).
reactPage routes have only a shell static body (renderReactShellPage: H1 = crumb, intro =
description); the React page replaces it. Menu pages (legacyFeature) come from
content/shared/navigation.yaml (see site-chrome-navigation).
The hub (/, kind home) is not rendered by the dispatcher: renderPublicHubDocument() fills
the Vite shell's <!--PUBLIC_HEAD--> / <!--PUBLIC_INDEX--> markers (see page-hub-home).
The build (pnpm build:cloudflare = astro build + scripts/astro-postbuild.ts)
astro.config.mjs (static output, base /angel-investments, srcDir: astro, flat ssr/<file>.html
names, Vite-style assets/ names, the same vendor chunks as before, @/@shared aliases). CI and
scripts/gate.ts run both commands; see .github/workflows/deploy-cloudflare.yml.
astro build:astro/pages/ssr/[...file].astrolists every manifest route (getStaticPaths), renders it withrenderStaticRoute()→preparePublicDocument()(head, body below the static header, crumb/footer/article for a React page), wraps it inDocument.astro+Chrome.astro, and renders a React page's component at build time: 18 stateless kinds with no directive (no JS), the four D3/canvas pagesclient:load, the restclient:idle.index.astrodoes the same for the hub withHomeas aclient:loadisland and the no-JS#public-indexafter#root.scripts/astro-postbuild.ts: themed CSS asset, allowlisted public assets,seo-route-manifest.json,source-reference-map.json,sitemap.xml,legacy-redirect-map.json,llms.txt,llms-full.txt,/data/*, the whole-document checks on every page (one canonical/title/JSON-LD/h1, content policy, every menu link), and the worker esbuild.
Local: pnpm build:cloudflare (or npx astro build && NODE_ENV=development npx tsx scripts/astro-postbuild.ts).
Parity against origin/main: pnpm parity (scripts/parity.ts; --all for every route and theme).
Local screenshots need the prefix proxy (see ui-before-after).
Rebuild order (all skills)
site-foundation(this) — manifest, dispatcher, render paths, build.site-chrome-navigation— header, sidebar, mobile tabs, footer, breadcrumbs, menu YAML.seo-head-and-schema— head tags, titles, canonical, JSON-LD, sitemap, llms, robots.theme-system— investor themes, CSS variables, hub views.i18n-locales— the English-only locale setup.new-react-page— the generic recipe every React page follows.- Page families:
page-hub-home→page-company→page-taxonomy→page-investors→page-vc-portfolios→page-editorial→page-angel-guides-reports→page-news→page-founders→page-status-sectors-markets→page-performance→page-research-tools→page-skills-and-agents. - Every change:
deploy-gate→ui-before-after→ship-to-production.
Cross-cutting rules: page-content-yaml (no copy in code), portfolio-counts-single-source,
private-data-boundary, public-url-conventions, project-architecture.
Tests
server/seo-route-manifest.test.ts (route kinds, reactPage routes), server/public-routing.test.ts,
server/public-react-document.test.ts, server/route-indexing.test.ts,
server/public-site.test.ts, server/content-in-yaml.test.ts, server/production-startup.test.ts.
Run them all through deploy-gate (scripts/gate.ts).