Core Backend Utilities

Core Backend Utilities provide the logic for data processing, metadata generation, and content management within the Astro-based website. These utilities handle domain-specific tasks such as SEO schema construction, navigation grouping, and resume data assembly to ensure consistent data structures across the application.

These utilities follow a modular architecture where pure helpers are colocated within domain-specific directories under src/features/. Each module typically includes a .utils.ts file for logic and a corresponding .test.ts file for verification.

Sources: AGENTS.md:73-82

SEO and Metadata Generation

The SEO utility generates structured data and JSON-LD graphs to improve search engine visibility. It maps internal content types to official Schema.org vocabularies and constructs a comprehensive graph containing website, page, and person information.

JSON-LD Graph Construction

The buildGraphJsonLd function creates a three-node graph. It combines website metadata, specific page details, and personal profile information into a single structured object.

The diagram above shows the composition of the JSON-LD graph from three distinct sub-generators.

Sources: src/utils/seo/schema.ts:88-93

Content Type Mapping

Content types from the site's frontmatter map to specific Schema.org types to provide context to crawlers.

Sources: src/utils/seo/schema.ts:7-13, src/utils/seo/schema.ts:68-76

Navigation and Routing Utilities

Navigation utilities transform site content and static configurations into structured link groups. They handle slug generation for test identifiers and distinguish between internal and external links.

Link Processing Logic

The system categorizes links into "Work", "Play", and "Live" groups. The "Live" group is dynamically populated from published pages, while others use static configurations.

This flow illustrates how static and dynamic content sources merge into the site's navigation structure.

Sources: src/features/navigation/navigation.utils.test.ts:31-48

Test Identifier Generation

To ensure stable E2E testing, utilities generate unique data-testid values. The toTestIdSlug function sanitizes paths by stripping leading slashes and converting directory separators into double hyphens (--) to prevent collisions with standard hyphens in filenames.

Sources: src/features/navigation/navigation.utils.test.ts:78-98

Resume Data Management

Resume utilities process YAML-based content collections into a structured format suitable for the UI. The logic includes sorting professional experience and filtering sections.

Data Assembly and Sorting

The assembleResumeData function organizes flat files into a nested object. It applies specific sorting rules to date-based entries:

• Experience: Sorted with current roles (null endDate) first, followed by historical roles in descending order.
• Awards/Dates: Sorted by date in descending order (newest first).

Sources: src/features/resume/resume.utils.test.ts:16-49

Page Filtering and SEO Resolution

Page utilities manage the visibility and metadata extraction for Markdown-based content.

Page Filtering

The buildPagesFilter function creates a predicate to exclude content from the site. It always hides files marked as draft: true and supports inclusive filtering based on IDs or directory paths.

Sources: src/features/pages/pages.utils.test.ts:25-42

SEO Priority Resolution

The resolvePageSeo utility determines which values to use for page metadata using a specific hierarchy:

1. SEO Overrides: Values found in the seo block of frontmatter.
2. Frontmatter Defaults: Standard title or description fields.
3. Rendered Content: Fallback to the HTML output for descriptions if no explicit fields exist.

Sources: src/features/pages/pages.utils.test.ts:51-86

Conclusion

The Core Backend Utilities standardize how data is transformed from raw content files and external APIs into the structured formats required by the Astro frontend. By centralizing logic for SEO, navigation, and resume management, the system maintains high data integrity and predictable behavior across the site.