Seed

Seed is a publishing site with a home page, article pages, categories, related posts, and comments. Editors create the content in a structured editing service called HyGraph. Readers visit the separate public site.

The main design question was what should happen between those two moments. An editor may change an article occasionally, while the finished article may be read many times. Seed avoids rebuilding the same page from the content service for every reader.

From an editor's publish action to a reader's page#

An article in HyGraph stores its title, body, image, author, slug, and category relationships. The slug is the readable part of its URL. Categories and authors are separate records, so several articles can point to the same category or author without copying their details.

During a deployment, Seed asks HyGraph for the known article and category slugs. Next.js then requests the content for each route and turns it into HTML. Preparing pages before visitors request them is static generation.

The completed HTML is cached and served to readers. A normal article visit therefore does not wait for HyGraph to answer or for React to assemble the main body in the browser.

flowchart TB
    E["Editor publishes an article in HyGraph"] --> Q["Next.js requests article data"]
    Q --> H["Build complete HTML"]
    H --> C["Store the prepared page in cache"]
    C --> R["Reader opens the article"]

Seed uses GraphQL for those content requests. GraphQL lets each screen name the fields it needs. The home page asks for card-sized article data; an article page asks for the full body, author, image, and categories; a category page asks for articles connected to one category.

Showing edits without rebuilding the whole site#

A prepared page can become old after an editor changes the article. Seed gives each route a refresh window. Once that time has passed, a request can start generating a newer copy. Until the new copy is ready, readers continue receiving the last completed page instead of waiting on an unfinished response.

Next.js calls this incremental static regeneration. In practical terms, the site keeps the speed of a prepared page while allowing that page to be replaced after publishing.

The home page used a longer refresh window than article and category pages. That was a product decision rather than a framework rule: an individual article is more likely to need a recent correction, while a slightly older home listing is less disruptive.

Publishing a new article after deployment#

The build can prepare only the slugs that exist at that time. An editor may add a completely new article later, before another deployment runs.

For a valid slug that has not been built yet, Seed generates the page on the first request and waits until that page is complete before responding. The completed result is cached for later visitors. Next.js calls this a blocking fallback.

This avoids returning “not found” until the next deployment, while also avoiding a live content query on every visit. The trade-off is that the first reader of a new slug pays the generation time.

If I rebuilt this flow now, a signed publishing webhook could request the new page as soon as the editor publishes it. The page would still be prepared once and reused; the editor's action, rather than the first reader, would trigger that work.

Loading the article and its supporting sections#

The main article body is part of the prepared HTML. Recent posts, related posts, categories, and comments were requested later from the browser.

That means the article remains readable if one of those secondary requests fails. It also means supporting sections can appear after the layout has loaded, each visitor repeats similar requests, and search engines do not receive all of that context in the initial HTML.

The related-post query itself is specific: it looks for articles sharing a category with the current article and excludes the current slug. The data request follows what that screen needs instead of downloading the full content store.

A rebuild would keep the article in the initial HTML and prepare more of the useful supporting content with it. Recent and related posts are secondary, but they are still predictable at page-generation time.

From comment submission to publication#

Reading an article uses public cached data. Submitting a comment changes shared content and needs a private credential, so it follows a different route.

The browser sends the commenter's name, email, text, and article slug to a Next.js API endpoint. That endpoint holds the private HyGraph token. It creates a comment connected to the article but leaves the comment unpublished.

An editor reviews the draft in HyGraph and chooses whether to publish it. Public comment queries return only published records. The content editor therefore doubles as the moderation screen.

sequenceDiagram
    participant R as Reader
    participant S as Seed server
    participant H as HyGraph
    participant E as Editor

    R->>S: Submit a comment for an article slug
    S->>S: Check the submitted fields
    S->>H: Create an unpublished comment
    H-->>S: Draft comment created
    S-->>R: Confirm receipt
    E->>H: Review and publish the draft
    R->>H: Request published comments
    H-->>R: Return the approved list

Keeping the token on the server prevents browser code from using the private credential directly. The archived route still needed stricter field validation, rate limiting, spam controls, clearer email handling, and better failure feedback. Manual review stops an unwanted comment from appearing immediately; it does not protect the submission endpoint by itself.

Before publishing another version#

I would keep prepared pages for the public reading path and connect publishing events to targeted page refreshes. Article-side recommendations and category context would move into the generated HTML where possible. Content responses would be checked against explicit schemas before page generation.

The comment route would receive the larger change: validated input, abuse controls, a clear privacy policy for email addresses, and observable errors when HyGraph rejects a write.

The request path remains separated by responsibility. Editors write structured content; deployments or publishing events prepare pages; readers reuse those pages; and the smaller set of operations that change shared data pass through a trusted server.