How it's built

Start here

The rewrite keeps the same public article URLs. Readers should not notice the CMS change. I should notice it every time I write.

Posts live in MongoDB. The admin is built for technical posts with real code blocks. The Next.js app ships through GitHub Actions. Authoring and Shipping below go into those two paths.

Philosophy

• One admin. A handful of careful posts. I needed a publishing tool for me, not a CMS for a team that does not exist. No users table. No roles. No page builder.
• If it does not help writing, it does not ship. No ORM. No plugin system I will never use. A dependency has to make authoring safer or clearer, or it stays out.
• Keep the routes thin. Pages render. Publishing rules live in services. Repositories talk to MongoDB. Secrets and ObjectId values stay on the server.
• Do not break the bookmarks. Existing article paths stay at /slug/. I can change how content is stored. I cannot casually change what people already share.

Did I use AI?

Yes. It is 2026. I used large language models on this project, and I would not pretend otherwise.

What I did not do is throw prompts at a chat box until something sorta worked. That approach produces code that looks finished and falls apart the first time you read it.

I wrote the plans first: what the product is, how the data should look, what to build next. Then I mixed hand coding and agent help, and reviewed the result as I went. Project docs and rules kept the model from wandering. I still own every choice on this page.

The LLM is a tool in the workflow, not the workflow itself.

Stack

Next.js App Router

App Router with Server Components by default. Client JavaScript only where the Lexical editor actually needs the browser.

TypeScript

TypeScript for strict typing across routes, services, and the shapes we store in MongoDB.

MongoDB Atlas

Where posts and their revisions live in Atlas. Official Node.js driver. No ORM.

Zod

Zod checks untrusted form and action input on the server before anything hits the database.

Lexical

Lexical editor state for drafts and published versions of an article.

Shiki

Shiki for syntax highlighting on public code panels. Same look you see in the articles.

Storybook

Storybook runs locally with the shared primitives and composites so I can keep those components organized and visually inspectable.

GitHub Actions

GitHub Actions validates on pull requests and main (format, lint, unit tests, build, E2E), then deploys main when those checks pass.

Runtime

Cloudflare in front, reverse proxy to Next.js, MongoDB Atlas for data.

Components

The public site and the admin share the same buttons, type, and cards. If I change how a heading looks, it should change on an article card and in the editor, not in two places that happen to match.

The small controls live in src/components/ui/. Bigger blocks that more than one page needs live one folder down in composites/. Storybook is where I look at them without loading a whole page.

• Primitives Button, Badge, TextLink, TextField, InlineCode, Heading, and Text. Article cards and the post editor import the same files.
• Composites Callout, TopicCard, Breadcrumb, SectionToc, CodePanel, and GuideCard. They stay presentational. Home cards, search, and this page wrap them with the data they need.
• Storybook I run npm run storybook locally on port 6006. Each story sits next to its component, so I can inspect a GuideCard or a CodePanel without opening the site. Deploys also build a static catalog for the same stories.

Architecture

Say you open /world-cup-finding-the-goal-with-match/ looking for a $match example. The app looks up that slug, checks that the article is published, loads the published version, and renders it. If I have only saved a draft, you get a 404. Unfinished edits stay off the public site.

Under the hood it is a thin stack: pages call services, services call repositories, repositories talk to MongoDB with the official Node.js driver. Publishing logic stays out of the UI so the routes can stay boring. The Database section below walks through the actual documents and fields.

Browser
   │
   ├─ Public pages (Server Components)
   └─ Admin (Lexical Client Components)
            │
            ▼
     Server Actions
            │
            ▼
        Services
     (publish, drafts, slugs)
            │
            ▼
      Repositories
            │
            ▼
      MongoDB Atlas
       posts + postRevisions

Why it's built this way

• Publishing adds a new version. It does not overwrite the old one. Each publish creates a new revision document. The previous one stays in the database. The live article just points at whichever revision is current.
• Drafts and the public page are separate. I can keep editing a draft without changing what readers see until I publish again.
• Trusted HTML is derived on the server. The browser is not the authority for article HTML. Validated Lexical JSON is what we store for editing; the server builds the HTML the public site renders.
• Content integrity is not a deploy concern. Releasing the app and changing articles are different workflows. A code deploy is not allowed to wipe or rewrite the post library.
• ObjectId values and Dates stay on the server. Client Components get strings. Same class of gotcha as making sure a TTL field is a real Date, not a string that only looks like one.

Authoring

WordPress gave me an admin too. What it did not give me was an editor that treated a mongosh example as first-class content instead of something a theme might mangle on the way out.

The editor is Lexical. Code blocks are first-class (language included), and public pages highlight them with Shiki. Save Draft and Publish are explicit. Preview stays behind an authenticated path so unfinished work does not leak. Every Save Draft, Publish, restore, or delete checks auth again on the server. The UI is not trusted as a gate.

Each of those actions inserts a new immutable revision. Lexical JSON is the editing source; the revision also carries the HTML and plain text the server derived for that save.

Shipping code

Application code ships through GitHub Actions. Pull requests and pushes to main run validation: format check, lint, unit tests, build, and E2E. Deploy runs from main after those jobs succeed.

That pipeline only updates the Next.js app. Publishing still happens in the admin against MongoDB. The deploy job is not a content migration.

Code spotlights

const revision = await insertRevision({
  postId,
  revisionNumber,
  type: "publish",
  title,
  slug,
  excerpt,
  content, // lexical + derived html + plainText
  seo,
  createdBy: "admin",
});

await updatePostById(postId, {
  currentDraftRevisionId: revision._id,
  publishedRevisionId: revision._id,
  status: "published",
  publishedAt,
});

export function serializePost(post: PostDocument) {
  return {
    id: post._id.toHexString(),
    slug: post.slug,
    status: post.status,
    currentDraftRevisionId:
      post.currentDraftRevisionId.toHexString(),
    publishedRevisionId:
      post.publishedRevisionId?.toHexString(),
    publishedAt: post.publishedAt?.toISOString(),
    // …
  };
}

const RESERVED_POST_SLUGS = [
  "admin",
  "articles",
  "book",
  "how-its-built",
  // …
] as const;

if (isReservedPostSlug(slug)) {
  return { ok: false, error: "This slug is reserved." };
}

Where concepts live

There is no public tutorial repo to wander through here. When I need to find something, I think in layers.

Where to go next

Learn Mongo, VerseSee, and the AI image search app share a pattern: server-first Next.js, MongoDB as the source of truth, thin routes that call services and repositories, and a How it's built page that explains the choices in public.

Want more MongoDB from here, or the same kind of behind-the-scenes write-up on those other projects?

• ArticlesPractical MongoDB posts on the public site.
• MongoDB for JobseekersThe book page with overview and buy links.
• AI Image Search: How it's builtKeyword, vector, and hybrid search over AI-enriched image metadata in MongoDB.
• VerseSee: How it's builtA scripture-first exhibit app with the same server-first MongoDB approach.
• LinkedInQuestions about the work? Find me there.