Generated using AI. Be aware that everything might not be accurate.


Chapter 1: Architecture Overview

The Fundamental Challenge

Static websites are, by definition, static. They consist of pre-generated HTML, CSS, and JavaScript files served directly from a web server or CDN. There’s no server-side processing when a visitor requests a page. Comments, however, are inherently dynamic—they’re created by users after the page is published.

This chapter explores the architectural approaches to bridging this gap.

Architecture Patterns

Pattern 1: API Backend + Frontend Widget

The most common approach involves a separate backend service that handles comment storage and retrieval, with a JavaScript widget on your static site that communicates with this backend.

How it works:

  • Your static site includes a JavaScript file
  • When the page loads, the script fetches comments from your API
  • When users submit comments, the script sends them to your API
  • The API handles storage, spam checking, and moderation

Advantages:

  • Clean separation of concerns
  • Comments load asynchronously (doesn’t slow initial page load)
  • Can be hosted on serverless platforms for low cost
  • Easy to add features like real-time updates

Disadvantages:

  • Requires maintaining a separate service
  • JavaScript required for viewing comments
  • Additional latency for comment loading
  • Cross-origin considerations

Pattern 2: Git-Based Comments

This approach treats comments as part of your site’s source code, storing them in your Git repository and rebuilding the site when new comments are approved.

How it works:

  • Comments are submitted via a form or API
  • Submissions create pull requests or issues in your repository
  • After moderation/approval, the site rebuilds with new comments
  • Comments become part of the static HTML

Advantages:

  • No separate backend to maintain
  • Comments are truly static (no JavaScript needed to display)
  • Built-in version control and audit trail
  • Works with existing CI/CD pipelines

Disadvantages:

  • Comments aren’t real-time (delay until rebuild)
  • Moderation workflow can be cumbersome
  • Repository size grows with comments
  • Limited interactive features

Pattern 3: Serverless Functions

A lightweight approach using serverless functions (AWS Lambda, Cloudflare Workers, Netlify Functions) to handle comment operations.

How it works:

  • Serverless functions handle comment submissions
  • Comments stored in a database or file storage
  • Functions triggered by HTTP requests from your site
  • Pay only for actual usage

Advantages:

  • No server to maintain
  • Scales automatically
  • Potentially very low cost for low-traffic sites
  • Easy deployment alongside static site

Disadvantages:

  • Cold start latency can affect user experience
  • Vendor lock-in concerns
  • Debugging can be more challenging
  • Function execution limits may apply

Pattern 4: Static JSON Files

The simplest approach: store comments as static JSON files that are loaded by the browser.

How it works:

  • Comments stored as JSON files (one per page or post)
  • Browser fetches and renders these files
  • New comments submitted to an endpoint that updates the JSON
  • File can be served from CDN

Advantages:

  • Extremely simple to implement
  • Very fast comment loading (CDN-cached)
  • Minimal infrastructure
  • Easy to backup and migrate

Disadvantages:

  • Concurrent write issues
  • No real-time updates without polling
  • All comments loaded at once (pagination challenges)
  • Manual or automated process needed to update files

Pattern 5: Third-Party Backend with Self-Hosted Frontend

A hybrid approach using a managed database service while controlling the frontend and API logic yourself.

How it works:

  • Use a managed database (Firebase, Supabase, PlanetScale)
  • Write your own API layer or use database’s built-in API
  • Full control over frontend display
  • Database provider handles scaling and availability

Advantages:

  • Reduced operational burden
  • Professional-grade database infrastructure
  • Often generous free tiers
  • Focus on features, not infrastructure

Disadvantages:

  • Some vendor dependency
  • Data stored on third-party infrastructure
  • Pricing can be unpredictable at scale
  • Less control over data layer

Choosing Your Architecture

Decision Factors

Traffic Volume:

  • Low traffic: Any approach works; simpler is better
  • Medium traffic: Consider serverless or managed backend
  • High traffic: Need careful attention to scaling and caching

Technical Resources:

  • Limited: Git-based or static JSON approaches
  • Moderate: Serverless functions
  • Strong: Full API backend

Feature Requirements:

  • Basic comments only: Static JSON or Git-based
  • Real-time features: API backend with WebSockets
  • Rich threading: Full API backend recommended

Budget:

  • Minimal: Git-based or static JSON
  • Low: Serverless with managed database
  • Moderate: Full API backend on VPS or containers

Hybrid Approaches

You don’t have to choose just one pattern. Many successful implementations combine approaches:

  • API + Static Caching: Use an API backend but cache rendered comments as static files
  • Serverless + CDN: Serverless functions for writes, CDN-cached files for reads
  • Git-Based + Real-time: Store in Git for permanence, but show pending comments via API

System Components

Regardless of which architecture you choose, your system will need these logical components:

Comment Submission Endpoint

Receives new comments from users, validates them, and initiates storage.

Storage Layer

Persists comments durably. Options discussed in detail in Chapter 2.

Retrieval Mechanism

Fetches comments for display on pages. Must be fast and cacheable.

Moderation Interface

Allows you (or moderators) to review, approve, edit, or delete comments.

Display Component

Frontend code that renders comments on your pages.

Spam Filter

Checks submissions for spam before storage. Detailed in Chapter 4.

Notification System (Optional)

Alerts users to replies or you to new comments.

API Design Considerations

If your architecture includes an API, consider these design decisions:

RESTful vs. GraphQL

  • REST is simpler and well-understood
  • GraphQL offers flexibility but adds complexity
  • For most comment systems, REST is sufficient

Endpoint Structure

  • Per-page endpoints: /api/comments/{page-id}
  • Bulk endpoints: /api/comments?page={page-id}
  • Consider how pagination and threading affect design

Response Format

  • JSON is the standard choice
  • Consider including metadata (total count, pagination info)
  • Consistent error response structure

Rate Limiting

  • Essential for preventing abuse
  • Implement at the API level
  • Consider per-user and per-IP limits

Data Flow Patterns

Write Path (Submission)

  1. User submits comment
  2. Frontend validates basic requirements
  3. Backend receives submission
  4. Spam check performed
  5. Comment stored (pending or approved)
  6. Confirmation returned to user
  7. Notification sent (if applicable)

Read Path (Display)

  1. Page loads
  2. Frontend requests comments
  3. Backend retrieves from storage
  4. Comments returned (possibly cached)
  5. Frontend renders comments
  6. Pagination handled if needed

Moderation Path

  1. New comment triggers notification
  2. Moderator reviews in moderation interface
  3. Decision made (approve/reject/edit)
  4. Comment status updated
  5. Public display updated accordingly

Scalability Considerations

Vertical Scaling

Adding more resources to a single server. Simple but has limits.

Horizontal Scaling

Adding more servers. Requires stateless design and load balancing.

Caching Layers

  • Browser caching
  • CDN caching
  • Application-level caching
  • Database query caching

Database Scaling

  • Read replicas for high-read workloads
  • Sharding for very large datasets
  • Consider comment archiving strategies

Summary

The architecture you choose sets the foundation for everything else. Consider:

  • Your technical capabilities and time availability
  • Expected traffic and growth patterns
  • Feature requirements now and in the future
  • Budget constraints
  • Tolerance for operational complexity

Most personal blogs and small sites can start with the simplest approach (static JSON or serverless) and evolve as needs grow. The key is choosing an architecture that you can implement, maintain, and afford.

The next chapter dives deep into storage strategies, exploring where and how to persist your comment data.


>> You can subscribe to my mailing list here for a monthly update. <<