Merge pull request #24 from psatomas/refactor/research-repository-abstraction

refactor(research): introduce a repository abstraction behind the public pages

Author: psatomas

src/app/research/[slug]/page.tsx

@@ -1,15 +1,9 @@
 import Link from "next/link";
 import { notFound } from "next/navigation";
-import type { ComponentType } from "react";
 import { Container } from "@/components/ui/container";
 import { MonoLabel } from "@/components/ui/mono-label";
 import { Tag } from "@/components/ui/tag";
-import {
-  getAdjacentResearchArticles,
-  getAllResearchArticles,
-  getResearchArticleBySlug,
-} from "@/lib/research";
-import type { ResearchArticleMetadata } from "@/types";
+import { researchRepository } from "@/lib/research";
 
 // Prerenders every known article at build time — same as
 // /projects/[slug]. Deliberately NOT setting `dynamicParams = false` here:
@@ -21,7 +15,7 @@ import type { ResearchArticleMetadata } from "@/types";
 // /projects/[slug]/page.tsx already does successfully in production — is
 // the pattern actually proven to work on this stack.
 export async function generateStaticParams() {
-  const articles = await getAllResearchArticles();
+  const articles = await researchRepository.getPublishedArticles();
   return articles.map((article) => ({ slug: article.slug }));
 }
 
@@ -40,17 +34,15 @@ export default async function ResearchArticlePage(
 ) {
   const { slug } = await props.params;
 
-  const known = await getResearchArticleBySlug(slug);
-  if (!known) notFound();
+  // The page asks the repository for an article and either gets a fully
+  // renderable one back or doesn't — it never knows or cares whether that
+  // meant a slug lookup in an array, a file import, or (eventually) a D1
+  // query for a row with status = 'published'.
+  const article = await researchRepository.getPublishedArticleBySlug(slug);
+  if (!article) notFound();
 
-  const { default: Article, metadata } = (await import(
-    `@/content/research/${slug}.mdx`
-  )) as {
-    default: ComponentType;
-    metadata: ResearchArticleMetadata;
-  };
-
-  const { newer, older } = await getAdjacentResearchArticles(slug);
+  const { Content } = article;
+  const { newer, older } = await researchRepository.getAdjacentPublishedArticles(slug);
 
   return (
     <Container as="main" className="flex flex-1 flex-col gap-10 py-16">
@@ -63,32 +55,32 @@ export default async function ResearchArticlePage(
 
       <div className="flex flex-col gap-3">
         <MonoLabel className="text-dim">
-          RESEARCH / {metadata.category}
+          RESEARCH / {article.category}
         </MonoLabel>
         <div className="flex flex-wrap items-center gap-3">
           <MonoLabel className="text-dim">
-            {formatArticleDate(metadata.date)}
+            {formatArticleDate(article.publishedAt)}
           </MonoLabel>
           <span className="text-dim">·</span>
-          <MonoLabel className="text-dim">{metadata.readingMinutes} MIN READ</MonoLabel>
+          <MonoLabel className="text-dim">{article.readingMinutes} MIN READ</MonoLabel>
         </div>
         <h1 className="text-3xl font-semibold tracking-tight sm:text-4xl">
-          {metadata.title}
+          {article.title}
         </h1>
-        <p className="max-w-xl text-lg text-muted">{metadata.description}</p>
+        <p className="max-w-xl text-lg text-muted">{article.description}</p>
       </div>
 
       <div className="flex flex-col gap-3 border-t border-border pt-8">
         <MonoLabel>ARTICLE</MonoLabel>
         <div className="max-w-xl">
-          <Article />
+          <Content />
         </div>
       </div>
 
       <div className="flex flex-col gap-3 border-t border-border pt-8">
         <MonoLabel>TAGS</MonoLabel>
         <div className="flex flex-wrap gap-2">
-          {metadata.tags.map((tag) => (
+          {article.tags.map((tag) => (
             <Tag key={tag}>{tag}</Tag>
           ))}
         </div>

src/app/research/page.tsx

@@ -1,10 +1,10 @@
 import Link from "next/link";
 import { Container } from "@/components/ui/container";
 import { MonoLabel } from "@/components/ui/mono-label";
-import { getAllResearchArticles } from "@/lib/research";
+import { researchRepository } from "@/lib/research";
 
 export default async function ResearchPage() {
-  const articles = await getAllResearchArticles();
+  const articles = await researchRepository.getPublishedArticles();
 
   return (
     <Container as="main" className="flex flex-1 flex-col gap-10 py-16">
@@ -29,7 +29,7 @@ export default async function ResearchPage() {
             className="flex flex-col gap-2 border-t border-border py-8 first:border-t-0 first:pt-0"
           >
             <div className="flex items-center gap-3">
-              <MonoLabel className="text-dim">{article.date}</MonoLabel>
+              <MonoLabel className="text-dim">{article.publishedAt}</MonoLabel>
               <span className="text-dim">·</span>
               <MonoLabel className="text-dim">{article.category}</MonoLabel>
             </div>

src/lib/research.ts

@@ -0,0 +1,91 @@
+import type { ComponentType } from "react";
+
+/**
+ * Research's domain model — storage-independent on purpose. Nothing here
+ * knows about .mdx files or D1; both are just implementations of the
+ * repository interface in ./repository.ts. This is what lets the public
+ * pages depend on a shape instead of a source.
+ */
+
+/**
+ * The known Research categories — a closed union rather than a free
+ * string now that there's real content to base it on. Add a new one here
+ * deliberately, in the same commit as the article that needs it, rather
+ * than letting near-duplicate strings ("Protocol engineering" vs
+ * "Protocol Engineering") accumulate silently. Tags stay a free string[]
+ * — there's no fixed set of those, and no filtering feature yet that
+ * would need one.
+ */
+export type ResearchCategory = "EVM" | "Protocol Engineering" | "Distributed Systems";
+
+export type ArticleStatus = "draft" | "published";
+
+/**
+ * What the public UI actually consumes — always a published article, so
+ * `publishedAt` is never null here (contrast ResearchArticleRecord below,
+ * where a draft genuinely has no publish date yet). This is intentionally
+ * the same shape the MDX-backed content already had, just with `date`
+ * renamed to `publishedAt` to match the eventual stored record — the
+ * public pages don't need `status` or timestamps they never display.
+ */
+export type ResearchArticleMetadata = {
+  slug: string;
+  title: string;
+  description: string;
+  category: ResearchCategory;
+  tags: string[];
+  readingMinutes: number;
+  /** ISO date string, e.g. "2026-08-29" — sortable as-is. */
+  publishedAt: string;
+};
+
+/** Metadata plus the actual renderable body. `Content` is a component
+ * regardless of where the article came from: the MDX adapter gets it from
+ * a build-time file import, a future D1 adapter would get it by compiling
+ * the stored Markdown/MDX string into a component at read time. Either
+ * way, the page just renders `<Content />` and never knows which. */
+export type ResearchArticle = ResearchArticleMetadata & {
+  Content: ComponentType;
+};
+
+export type AdjacentArticles = {
+  newer: ResearchArticleMetadata | null;
+  older: ResearchArticleMetadata | null;
+};
+
+/**
+ * The full authoring-side record — every field a draft-to-published
+ * article needs, independent of MDX and D1. Not consumed by the public
+ * pages at all; exists so the eventual write operations (see
+ * ResearchAuthoringRepository) have a settled shape to work with before
+ * anything actually implements them. `content` is raw Markdown/MDX
+ * source — the editable, storable form — as distinct from `Content`
+ * above, which is that source already compiled into something renderable.
+ */
+export type ResearchArticleRecord = {
+  id: string;
+  slug: string;
+  title: string;
+  description: string;
+  category: ResearchCategory;
+  tags: string[];
+  content: string;
+  readingMinutes: number;
+  status: ArticleStatus;
+  /** Null until the article is published for the first time. */
+  publishedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+/** Fields an author actually provides when writing or editing a draft —
+ * everything on ResearchArticleRecord except what the system assigns
+ * itself (id, status, timestamps). */
+export type DraftInput = {
+  title: string;
+  description: string;
+  category: ResearchCategory;
+  tags: string[];
+  content: string;
+  readingMinutes: number;
+};

src/lib/research/domain.ts

@@ -0,0 +1,22 @@
+/**
+ * The composition root for Research's content access. This is the one
+ * line that decides where article data actually comes from — everything
+ * else (both public pages) imports `researchRepository` and the types
+ * below, never a concrete adapter. Switching to D1 later means changing
+ * this one line to `createD1ResearchRepository(...)`, not touching
+ * /research or /research/[slug] at all.
+ */
+import { createMdxResearchRepository } from "./mdx-repository";
+
+export const researchRepository = createMdxResearchRepository();
+
+export type {
+  AdjacentArticles,
+  ArticleStatus,
+  DraftInput,
+  ResearchArticle,
+  ResearchArticleMetadata,
+  ResearchArticleRecord,
+  ResearchCategory,
+} from "./domain";
+export type { PublicResearchRepository, ResearchAuthoringRepository } from "./repository";