Static-First Portfolio Architecture with Astro 7

The current portfolio is a static Astro 7 site. Projects and credentials live in JSON Content Collections, articles live in MDX, and all public routes are generated at build time. There is no runtime database, authentication flow, or admin route in the deployed application.

Why Static-First Fits the Content

Portfolio content changes through reviewed repository updates, not on every request. Building it into HTML and assets removes a network dependency from the public rendering path and makes every change inspectable in version control.

The content and build gates validate:

• project evidence categories and required flagship fields;
• credential types and verification status;
• dates, URLs, collection metadata, and image health.

The broader quality suite separately validates localized routes, reciprocal alternates, internal links, unit behavior, browser regressions, keyboard and responsive flows, security checks, and accessibility scans.

Collections as the Source of Truth

The project schema separates presentation from evidence. A flagship must include localized problem, role, decisions, result, and limitations. It also needs at least one typed evidence source or localized case-study route; a live site alone is not proof of role or impact.

const projectSchema = z.object({
  project_type: projectTypeSchema,
  evidence_status: projectEvidenceStatusSchema,
  capabilities: z.array(projectCapabilitySchema).min(1),
  domain: projectDomainSchema,
  translations: z.object({
    en: projectTranslationSchema,
    es: projectTranslationSchema,
  }),
});

Credentials use a different contract. verified, source-linked, and unverified are separate states; a public source is not presented as independent verification.

Routing and SEO

A typed route registry owns the EN/ES pairs, labels, canonical paths, alternates, indexability, page type, and OS routes. Navigation, taskbar links, locale switching, redirects, SEO markup, and the sitemap consume the same registry instead of maintaining parallel maps.

Interaction without a Runtime Backend

Astro renders the document and collection data. Svelte islands receive that data as props and handle local interactions such as project filters, accessible dialogs, persistent windows, media controls, and deterministic replays.

Filtering is synchronous and local. The project archive also mirrors active filters into the query string so a view can be revisited without introducing a backend.

Migration Scripts Are Not Application Architecture

The repository retains explicit one-time export scripts for historical Supabase content. They require local environment variables and are never imported by the public application. Their presence does not mean the deployed site uses Supabase at runtime.

Known Boundaries

The retro desktop is progressive enhancement, but some of its richer interactions require JavaScript. Physical Safari/iOS, VoiceOver, real browser zoom, and hosted response headers remain separate manual or Preview-level verification gates.

The Architecture in One Sentence

Version content and evidence in the repository, validate them at build time, render useful static HTML with Astro, and hydrate only the Svelte interactions that need browser state.