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
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
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:
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
- 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)
- User submits comment
- Frontend validates basic requirements
- Backend receives submission
- Spam check performed
- Comment stored (pending or approved)
- Confirmation returned to user
- Notification sent (if applicable)
Read Path (Display)
- Page loads
- Frontend requests comments
- Backend retrieves from storage
- Comments returned (possibly cached)
- Frontend renders comments
- Pagination handled if needed
Moderation Path
- New comment triggers notification
- Moderator reviews in moderation interface
- Decision made (approve/reject/edit)
- Comment status updated
- 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.