System Requirements

Functional Requirements:

• Users can create new tags.
• Users can rename or edit existing tags.
• Users can delete tags they no longer need.
• Users can attach one or more tags to any digital item.
• Users can search for items using one or more tags (intersection/union).
• The system provides tag suggestions based on prefix matching or behavior.
• The system normalizes tags (lowercasing, trimming, synonym mapping).

Non-Functional Requirements:

• High Read Scalability: The system must handle massive read volumes for search queries and autocomplete suggestions.
• Low Latency: Tag suggestions (autocomplete) must return in < 50ms to feel responsive as the user types.
• Eventual Consistency: While writes (tag creation/editing) must be strictly consistent, it is acceptable for the search index to lag by a few milliseconds (eventual consistency).
• High Availability: Search functionality should remain available even if the write database experiences temporary downtime.

Gemini said

This is a brilliant template for structuring system design documents. It is clean, covers all the critical architectural pillars, and is exactly the kind of artifact that demonstrates seniority in an engineering setting.

Here is the complete system design document for the Tagging System, adapting the CQRS (Command Query Responsibility Segregation) architecture we discussed into your format.

System Requirements

Functional Requirements:

• Users can create new tags.
• Users can rename or edit existing tags.
• Users can delete tags they no longer need.
• Users can attach one or more tags to any digital item.
• Users can search for items using one or more tags (intersection/union).
• The system provides tag suggestions based on prefix matching or behavior.
• The system normalizes tags (lowercasing, trimming, synonym mapping).

Non-Functional Requirements:

• High Read Scalability: The system must handle massive read volumes for search queries and autocomplete suggestions.
• Low Latency: Tag suggestions (autocomplete) must return in < 50ms to feel responsive as the user types.
• Eventual Consistency: While writes (tag creation/editing) must be strictly consistent, it is acceptable for the search index to lag by a few milliseconds (eventual consistency).
• High Availability: Search functionality should remain available even if the write database experiences temporary downtime.

API Design

To adhere to RESTful principles and CQRS, we separate the write operations (managing tags) from the read operations (searching and suggesting).

1. Create a Tag POST /v1/tags

JSON

2. Rename a Tag PUT /v1/tags/{tag_id}

JSON

3. Attach Tags to an Item POST /v1/items/{item_id}/tags

JSON

4. Search Items by Tags GET /v1/items?tags=system-design,java&operator=AND&limit=20&page=1 Returns a paginated list of items that contain both tags.

5. Suggest Tags (Autocomplete) GET /v1/tags/suggestions?q=sys&limit=5 Returns a list of suggested tags matching the prefix "sys".

Gemini said

This is a brilliant template for structuring system design documents. It is clean, covers all the critical architectural pillars, and is exactly the kind of artifact that demonstrates seniority in an engineering setting.

Here is the complete system design document for the Tagging System, adapting the CQRS (Command Query Responsibility Segregation) architecture we discussed into your format.

System Requirements

Functional Requirements:

• Users can create new tags.
• Users can rename or edit existing tags.
• Users can delete tags they no longer need.
• Users can attach one or more tags to any digital item.
• Users can search for items using one or more tags (intersection/union).
• The system provides tag suggestions based on prefix matching or behavior.
• The system normalizes tags (lowercasing, trimming, synonym mapping).

Non-Functional Requirements:

• High Read Scalability: The system must handle massive read volumes for search queries and autocomplete suggestions.
• Low Latency: Tag suggestions (autocomplete) must return in < 50ms to feel responsive as the user types.
• Eventual Consistency: While writes (tag creation/editing) must be strictly consistent, it is acceptable for the search index to lag by a few milliseconds (eventual consistency).
• High Availability: Search functionality should remain available even if the write database experiences temporary downtime.

API Design

To adhere to RESTful principles and CQRS, we separate the write operations (managing tags) from the read operations (searching and suggesting).

1. Create a Tag POST /v1/tags

JSON

2. Rename a Tag PUT /v1/tags/{tag_id}

JSON

3. Attach Tags to an Item POST /v1/items/{item_id}/tags

JSON

4. Search Items by Tags GET /v1/items?tags=system-design,java&operator=AND&limit=20&page=1 Returns a paginated list of items that contain both tags.

5. Suggest Tags (Autocomplete) GET /v1/tags/suggestions?q=sys&limit=5 Returns a list of suggested tags matching the prefix "sys".

High-Level Design

• Client: Web or mobile application making REST API calls.
• API Gateway / Load Balancer: Routes write requests to the Tag Management Service and read/search requests to the Search Service.
• Tag Management Service (Write Path): Handles business logic for creating, renaming, deleting, and normalizing tags. Ensures ACID compliance.
• Primary Database (PostgreSQL): The single source of truth. Stores the highly normalized relational data.
• CDC & Message Broker (Debezium + Kafka): Change Data Capture monitors PostgreSQL transaction logs and pushes mutation events to Kafka topics.
• Search Service (Read Path): Directly queries the search engine for lightning-fast item retrieval and autocomplete suggestions.
• Search Engine (Elasticsearch): Consumes messages from Kafka to update its inverted indices. Optimized purely for read performance, text analysis, and fuzzy matching.

Detailed Component Design

Let's dig into the core mechanics that make this hybrid architecture scale effectively.

1. The CQRS Paradigm & Eventual Consistency By decoupling reads and writes, we solve the "Rename Tag" bottleneck. When a user renames "java" to "java-8", the Tag Management Service updates exactly one row in PostgreSQL. Debezium captures this row update and publishes an event to Kafka.

An ingestion worker consumes this event and pushes the update to Elasticsearch. The read index is updated asynchronously, protecting the primary database from heavy read loads and complex join queries.

2. Tag Normalization and Synonyms Normalization happens in two phases:

• Write-time (API Layer): When a user submits a tag, the Tag Management Service immediately trims whitespace, converts it to lowercase, and replaces spaces with hyphens (e.g., " Spring Boot " -> "spring-boot"). This ensures the PostgreSQL database remains pristine.
• Read-time (Elasticsearch): Elasticsearch utilizes custom analyzers and token filters. We can define a synonym graph directly in ES, so when a user searches for "JS", the analyzer automatically expands the query to look for items tagged with "javascript", without needing to duplicate data in the primary database.

3. Real-Time Suggestions (Edge N-Grams) To achieve the < 50ms latency requirement for autocomplete, we avoid SQL LIKE '%prefix%' queries entirely. Instead, we configure Elasticsearch with an Edge N-gram tokenizer. As tags are indexed, they are broken down into prefix tokens (e.g., "sys", "syst", "syste", "system"). When the user types "sys", Elasticsearch performs a direct, constant-time exact match lookup against these tokens, returning results instantly.