>Projects>Lab>Workbench>Blueprints>Research>Now>Roadmap>Timeline>Learning>Artifacts>Blog
status: building

Blueprint · Content Architecture

Developer Lab CMS / Artifact System

A content system for managing projects, workbench notes, research papers, artifacts, blueprints, and timelines from typed data.

In ProgressMediumTypeScriptMDXContent LayerStatic RenderingInternal CMS
back to blueprints

Overview

The content system behind this personal site: typed data files and reusable templates that make projects, workbench notes, research, artifacts, blueprints, learning maps, and timeline entries feel connected.

Problem

A developer lab can quickly become scattered if each page invents its own data shape. The site needs one place to update content, consistent cards, reliable links, related content, and coming-soon states that do not break.

Core users

  • Site owner updating projects and notes
  • Readers navigating between projects, blueprints, and field notes
  • Future contributors or maintainers reviewing content structure
  • Search engines and feed readers consuming structured metadata

MVP scope

  • Typed content layer using TypeScript data files
  • Reusable cards for projects, workbench notes, blueprints, research, artifacts, and timeline entries
  • Detail templates for content that needs long-form rendering
  • Tags, status badges, and related links
  • Coming-soon artifact states without dead downloads
  • Cross-section homepage guide

Non-goals

  • Do not add a full hosted CMS before content shape stabilizes
  • Do not create download links for files that do not exist
  • Do not duplicate project summaries across many files without a reason
  • Do not make every rough note feel like a polished essay

Core system components

  • TypeScript data files for projects, workbench, blueprints, research, roadmap, timeline, learning, artifacts, and site navigation
  • Route templates for index and detail pages
  • Shared card components and status chips
  • Related content blocks
  • Tag and category taxonomy
  • Build-time link checks or route generation
  • Optional MDX renderer later

Suggested architecture

  • Content layer: typed TypeScript arrays first, with a possible migration path to MDX or a CMS later.
  • Pages: app router routes import the data and render static pages.
  • Templates: detail routes use the same content structures to avoid one-off layouts.
  • Links: internal related links point to real routes, and unavailable artifacts use Coming Soon states instead of fake hrefs.
  • Deployment: static rendering keeps the site fast and avoids a database for public content.
  • External APIs: none required for MVP.

Data model

  • Project: slug, title, tagline, description, status, categories, tags, github, live, caseStudy, year, priority
  • WorkbenchNote: slug, title, summary, date, tags, relatedProject, status, readTime, intro, goal, learnings, technicalNotes, openQuestions, nextSteps, relatedLinks
  • Blueprint: slug, title, summary, category, status, difficulty, tags, overview, problem, users, mvpScope, nonGoals, components, architecture, dataModel, apiDesign, technicalChallenges, tradeoffs, security, scalingPath, observability, futureFeatures
  • ResearchEntry: slug, title, topic, type, status, summary, tags, readHref, pdfHref, relatedProject
  • Artifact: slug, title, type, status, summary, href, related
  • TimelineItem and LearningTopic: structured entries for progression and study maps

API design

  • No runtime API is required in the MVP.
  • getProjectBySlug(slug) - resolve project detail data
  • getBlueprintBySlug(slug) - resolve blueprint detail data
  • getWorkbenchNoteBySlug(slug) - resolve note detail data
  • getRelatedContent(tags, relatedProject) - future helper for automatic cross-links
  • validateContentLinks() - future build-time integrity check

Key technical challenges

  • Avoiding duplicated content across pages
  • Keeping cross-links working as slugs change
  • Adding related content automatically without noisy false matches
  • Supporting coming-soon states cleanly
  • Keeping content easy to update
  • Preventing broken external links and missing internal routes

Tradeoffs

  • Use TypeScript data now because it gives type safety and low ceremony.
  • Avoid a CMS until the content model has stopped changing every week.
  • Keep rough workbench notes separate from polished blog essays so the site does not flatten all writing into one style.
  • Use static rendering before introducing search indexes or runtime content APIs.

Security considerations

  • Avoid user-submitted content in MVP.
  • Do not render unsafe HTML from content strings.
  • Keep external links explicit and use rel='noopener noreferrer'.
  • Do not expose draft private notes through public data files.
  • Check artifact hrefs before adding downloadable files.

Scaling path

  • Add MDX for long-form notes if TypeScript arrays become too large.
  • Add search across projects, notes, research, and blueprints.
  • Add generated feeds for workbench notes and blog posts.
  • Add build-time link validation.
  • Add an admin/editor surface only if content volume justifies it.

Observability

  • Build output should reveal route generation failures.
  • Future link checker can report broken internal and external hrefs.
  • Analytics can show which sections readers actually use.
  • Content freshness dashboard can flag stale roadmap or now entries.

Future features

  • MDX support
  • Site-wide search
  • RSS/JSON feeds
  • Automatic related content
  • Artifact download registry
  • Content linting