Design a Tagging Service

A tagging service is deceptively simple. CRUD operations on a many-to-many join table. But at 100M users applying tags to billions of items, three challenges surface: normalization (how "JavaScript" and "JS" become the same tag), search at scale (how to find all items with a tag across billions of associations), and hot tags (what happens when millions of users tag content with "WorldCup2026" simultaneously).

Functional

Create, edit, and delete tags: Users create new tags, rename existing ones, and delete tags they no longer need. Tag names are strings with a maximum length of 128 characters. The system normalizes all tag names at write time (lowercasing, trimming whitespace, resolving synonyms) so "JavaScript" and "JS" resolve to the same canonical tag.

The read-to-write ratio tells you everything. 50M tag writes per day versus 500M tag-based searches. This 10:1 ratio means the architecture must be heavily optimized for reads, caching and indexing dominate the design.

Traffic

Users: 100M registered users, 10M daily active users. Each active user performs roughly 5 tag operations per day (creating, assigning, or searching).

Two API patterns: write-side (tag CRUD and assignment) and read-side (search and suggestions). The write-side normalizes before storing. The read-side queries the search index, not the database.

Tag CRUD

POST /v1/tags: Create a new tag. Request body: name (string, required). The service normalizes the name (lowercase, trim, alias check) and returns the canonical tag with its tag_id. If the canonical form already exists, returns the existing tag with 200 OK. Creation is idempotent. This means clients do not need to check whether a tag exists before creating it.

Three data stores for three access patterns: PostgreSQL for tag metadata and relationships (ACID writes), Elasticsearch for search (fast reads), Redis for caching and autocomplete (low latency). Forcing all three patterns into one database means it performs poorly for two of them.

Why three stores instead of one? Consider what happens with PostgreSQL alone. Tag CRUD and assignment work perfectly. Relational databases excel at this. But tag search across 1B associations at 5,800 QPS requires inverted indices that PostgreSQL's GIN index cannot serve as efficiently as Elasticsearch. And autocomplete at sub-millisecond latency requires in-memory data structures that disk-based PostgreSQL cannot provide. Each store handles the access pattern it was designed for.

PostgreSQL Schema

Five components, one read/write split. Tag writes flow through the Tag Service to PostgreSQL, then asynchronously to Elasticsearch via Kafka. Tag searches hit Elasticsearch directly, never touching PostgreSQL. This decoupling means write failures never break search, and search load never affects writes.

Components

Two flows, different priorities. Tag assignment optimizes for correctness. Normalize before storing, never create duplicates. Search optimizes for speed. Query the inverted index, not the database. The async Kafka pipeline connects them. Understanding both flows reveals why the architecture separates the write path (PostgreSQL-centric) from the read path (Elasticsearch-centric) so aggressively.

Tag Assignment Flow

A user types "Java Script" with a space. Another types "javascript" lowercase. A third types "JS" as an abbreviation. Without normalization, these become three separate tags with three separate search results. The normalization pipeline is the GATE. It ensures one canonical tag regardless of how users express it.

Write-Time Normalization Pipeline

Three decisions shape the system: SQL vs NoSQL for the join table, flat vs hierarchical tags, and write-time vs read-time normalization. Each has a clear winner for this use case, but understanding the trade-offs shows when you would choose differently.

SQL (PostgreSQL) vs NoSQL (Cassandra) for item_tags

PostgreSQL wins for this workload. At 580 writes/sec, a single instance handles the volume easily. ACID guarantees prevent duplicate tag assignments. The unique constraint on (item_id, tag_id) enforces idempotency at the database level. Foreign keys ensure referential integrity (no orphaned tag associations). The dataset at 100GB fits comfortably in a well-provisioned instance with room to grow.

A tagging service fails gracefully. Tags are not financial transactions. But search index desync, cache failure, and hot tag storms each degrade the user experience in different ways. Understanding the failure modes tells you where to invest in monitoring and redundancy.

Search Index Desync

Elasticsearch falls behind PostgreSQL. Newly tagged items are invisible in search. This is the most common failure mode. Causes: Kafka consumer lag (consumer is slower than producers), Elasticsearch cluster health issues (yellow or red status), network partition between Kafka and Elasticsearch.

The system handles 500M tag searches per day with sub-100ms latency. The next improvements focus on reducing manual tagging effort, surfacing tag-based insights, and adding organizational structure.

ML-Based Auto-Tagging