Skip to content
All projects
Shipped

Klyro

A community blogging platform rebuilt from a second-year college project into something people could actually use.

On this page
Type
project

Built with

Overview

Klyro started in 2024 as a second-year MERN blog. v2 is a full rebuild: anyone can write, readers follow people and topics, discussions are threaded, a moderation team keeps things healthy, and it works as well on a phone as a desktop.

v2 is feature-complete and tested but not yet deployed; the live site still runs v1.

How it works

v2 is a from-scratch rewrite of a 2024 college MERN blog into a community platform: anyone can write, readers follow people and topics, discussions are threaded, and a moderation team keeps it healthy.

Writing — a Tiptap rich editor with Markdown shortcuts, autosaving drafts, scheduled publishing, up to five tags per post with AI tag suggestions, and series that group posts into numbered collections.

Community — follow people and tags, two reaction types, bookmarks organised into collections, threaded comments with @mention autocomplete, and a share menu with server-rendered Open Graph / JSON-LD previews.

Discovery — Following / Latest / Trending feeds with infinite scroll. Trending weighs views, reactions, comments and bookmark age: (views·0.1 + likes + helpful·2 + comments·1.5 + bookmarks·1.5 + 1) / (hours + 2)^1.5, recomputed every 10 minutes.

Guest mode — "Continue as guest" starts a temporary account that can follow, react, bookmark and try the editor, but needs a full account to publish, comment or upload — that's what keeps spam out. Unclaimed guest accounts are deleted after 24 hours by a background job.

AI features (TL;DR summaries, tag suggestions, related-post embeddings) are optional and degrade gracefully: no key means keyword matching and no summaries, not a broken feature.

Architecture

One Node/Express process behind a React SPA, with Socket.io for real-time delivery and BullMQ for everything that shouldn't block a request:

Browser (React + TanStack Query, Redux for auth/UI only)
  │  REST /api (httpOnly cookies, X-Requested-With header)
  ▼
Express — Helmet · CORS · rate limits · CSRF header · JWT auth · Zod validation
  │
  ├─ Routes → Controllers (thin) → Services (business logic) → Mongoose models → MongoDB
  ├─ Socket.io — per-user rooms, pushes notifications
  └─ BullMQ workers — email, AI enrichment, scheduled posts, trending recompute, weekly digest
                       (no Redis → same jobs run in-process; only caching is lost)

Each route declares its access level (public/user/writer/moderator/admin) and Zod schema in one place, and that same declaration generates the OpenAPI spec — docs can't drift from the code because they're the same code.

Design choices worth defending:

  • Cursor pagination everywhere a list grows — feeds, comments, notifications, bookmarks, moderation — with opaque base64url({ value, id }) cursors backed by compound indexes, not page numbers.
  • Denormalized counters (likes, comments, followers) updated with $inc alongside the write that caused them, so a feed read is one query instead of a join-and-count.
  • Redis cache is optional, not load-bearing. Hot posts (60s), first page of public feeds (30s), profiles and trending tags are cached and invalidated on write — but nothing breaks if Redis is absent, it just gets slower.
  • Server-rendered SEO without server-side rendering. The SPA's index.html gets page-specific title/OG/Twitter/JSON-LD tags injected per route, so link previews work without standing up SSR.

v1 architecture (currently live)

The architecture of the deployed v1 — Firebase/Google auth, Redux, Express REST API, MongoDB. Generated via GitDiagram (gitdiagram.com) by Ahmed Khaleel, from the mern-blog repo's main branch. v2 (described in the sections above) replaces Firebase auth with JWT cookies and adds Socket.io + BullMQ, but is not deployed yet — this diagram shows what is actually live today, not v2.

Testing

63 automated tests: 47 Jest + Supertest API tests against an in-memory MongoDB (auth token rotation and reuse detection, CSRF, drafts and sanitization, cursor pagination, follows/reactions/bookmarks, nested comments and mentions, guest-mode limits and expiry, moderation role hierarchy), plus 16 Vitest + React Testing Library UI tests.

Before release, v2 was also driven end-to-end in a real browser with Playwright: 20 user flows from sign-up to password reset on phone and desktop viewports, with real-time notifications and email actually firing. A separate responsive audit loaded every page at seven viewport widths from 320px to 1920px checking for horizontal overflow, tiny tap targets and console errors. Both passed against the production Docker build, not a dev server.

CI runs lint → typecheck → test → build, then confirms the Docker image itself builds.

Decisions

Guest mode had to not become a spam vector. The fix wasn't clever detection — it's structural: guests can do everything read-and-react, nothing write-and-visible (publish, comment, upload), and the account self-destructs in 24 hours unless claimed. No spam classifier to maintain, no false positives to apologize for.

Trust the server, not the client, for identity. v1 trusted whatever email Google's client-side flow handed it. v2 verifies the Google ID token server-side instead — a deliberate correction of a real v1 weakness, not a hypothetical one.

Migration had to be safe to run twice. npm run migrate:v1 is idempotent by design (dry-run by default, --apply to write), because a migration script you're afraid to re-run is a migration script you'll eventually run wrong.

Results

v2 is feature-complete and fully tested but not yet deployed — the live site still runs v1 from main, with v1 kept as a backup branch. That's a real, current state, not a stale note: the honest answer to "is it live" is no, by choice, until the migration path has been exercised against the live database.

What does exist and is verified: 63 passing automated tests, a clean Playwright run across 20 flows, a responsive audit across seven breakpoints, and an idempotent migration script that converts v1's MongoDB collections in place without breaking existing /post/<slug> links or v1 passwords.