Unified Tagging System for Atlassian Products #

This note models a unified tagging system across Jira tickets, Confluence documents, and Bitbucket pull requests where users can add or remove tags on any supported content, click a tag to see associated items across products, and view a dashboard of the top K most popular tags.

Step 1 - Normalize #

Assume the baseline prompt is:

• design a unified tagging system across multiple Atlassian products
• users can add, remove, and update tags on content
• clicking a tag shows all tagged items across products
• users can see the top K most popular tags
• tagging should work across Jira, Confluence, and Bitbucket

Normalize into state-affecting paths.

Notes on normalization #

Important choices:

• add/remove tag is modeled as TagAssignment lifecycle change
• tag rename/update is current-value tag metadata
• cross-product tag search is a source read over tag-to-content edges
• top K is a derived popularity view, not primary truth
• popularity maintenance is explicit because it is user-visible but derived

This system is a hybrid of:

• cross-object relationship state
• shared metadata/catalog state
• derived ranking view

Step 2 - Critical Path Selection #

Baseline critical paths #

Main C1 paths:

• P1 add tag
• P2 remove tag
• P3 update tag metadata
• P4 update tag popularity stats
• P5 route to shard owner
• P6 reassign shard ownership

Main R1 paths:

• P7 list items by tag
• P8 read top K tags
• P9 resolve content references

This design is driven by:

• one authoritative tag-assignment truth per content-tag edge
• shared tag identity across products
• derived top-K popularity

Step 3 - Primary State Extraction #

For a unified tagging system, the minimal primary state is tag metadata, content-tag assignment state, content references, popularity stats, and routing/ownership state.

Important modeling choices #

TagDefinition #

Primary because:

• shared tag identity and display metadata need one source of truth
• fields may include:
  • tag_id
  • display_name
  • normalized_name
  • color
  • created_by

TagAssignment #

This is the core cross-product relationship object.

Fields likely include:

• tag_id
• content_type
• content_id
• product
• state
• added_by
• added_at

Lifecycle:

• ACTIVE
• REMOVED

ContentReference #

Primary because:

• cross-product results need a normalized representation of content for listing
• may be hydrated from product systems or mirrored into this system

TagStats #

Primary because:

• top-K needs a stable count source, even if eventually reflected into a projection

Minimal strict primary set #

The strongest minimal set is:

• TagDefinition
• TagAssignment
• ContentReference
• TagStats
• PartitionOwnership
• PartitionMap

Step 4 - Hard Invariants #

For a unified tagging system, the hard invariants are about one authoritative assignment state per tag-content edge, correct shared tag metadata, and accurate popularity accounting derived from active assignments.

What matters most #

1. One authoritative assignment per tag-content edge #

This prevents duplicate add/remove confusion.

2. Popularity must count active assignments only #

Removed tags should not continue inflating top-K.

3. Top K is derived #

Exact tag-assignment truth matters more than instant ranking freshness.

4. Cross-product content identity must normalize cleanly #

The system needs a stable content_ref abstraction across Jira, Confluence, and Bitbucket.

Step 5 - Execution Context #

For the baseline unified tagging system:

Derived implications #

• holder_may_crash = false

  • clients may fail, but no lock-style ownership is central here

• cross_service_write = true-ish logically

  • the tagging service may need to validate or hydrate content from product systems
  • but authoritative tag truth should remain inside one logical tagging service

• bounded_staleness_allowed = true

  • projections like top-K and cached content display can be slightly stale

• cross_service_atomicity_required = false

  • no cross-product distributed transaction is required in the baseline

• exclusive_claim_required = true

  • shard ownership still needs one current owner

• guarded_by_current_state = true

  • add/remove transitions depend on current assignment state

What this implies #

This pushes us toward:

• one authoritative owner per tenant/tag shard
• current tag and assignment state inside the shared tagging service
• popularity as derived maintained state
• content hydration through normalized references

Step 6 - Deterministic Mechanism Selection #

Why these fit #

Add/remove tag #

These are current-state transitions on an assignment edge, so guarded transitions fit.

Tag metadata #

Current display identity is current-value state, so overwrite fits.

Popularity stats #

Popularity can be maintained either:

• by idempotent increment/decrement deltas
• or by periodic recompute from assignments

In practice:

• TagStats is current-value state
• fed by assignment deltas

Top K #

Top K is clearly a derived projection.

Canonical substrate implied #

The baseline now points to:

• sharded tagging service
• one owner per tag or tenant shard
• current tag definitions and assignment edges
• derived popularity stats and top-K view

Step 7 - Read Model / Source of Truth #

For a unified tagging system, truth is mostly direct source state for tags and assignments. Top K is derived.

Important point #

For the core semantics:

• tag-to-content listing should read authoritative assignments
• top-K can come from a derived projection
• content display can come from a normalized cache or hydration layer

Step 8 - Failure Handling #

What matters most #

1. Idempotent add/remove semantics #

Tagging UX often retries. The same add should not create duplicate active edges.

2. Popularity can be rebuilt #

TagStats and top-K are derived; assignment truth is primary.

3. Cross-product display hydration is secondary #

If content titles lag slightly, the tagging system can still be correct.

4. Rename semantics need product choice #

If tag rename changes the display for all products, TagDefinition should be global/shared within the tenant scope.

Step 9 - Scale Adjustments #

What scales well #

This system scales by:

• sharding tag and assignment state by tenant/tag key
• keeping tag assignments as compact edges
• deriving top-K from maintained stats
• caching normalized content references

What fails first #

Usually:

• a few very hot tags
• expensive cross-product hydration
• recomputing popularity from scratch too often
• large fanout result sets for global tags

Canonical design conclusion #

The mechanical outcome is:

• primary state:
  • TagDefinition
  • TagAssignment
  • ContentReference
  • TagStats
  • PartitionOwnership
  • PartitionMap
• critical invariants:
  • one authoritative assignment state per tag-content edge
  • current tag metadata by version
  • popularity counts equal active assignments
  • exclusive shard ownership for tag truth
• mechanisms:
  • guarded add/remove transitions
  • overwrite current tag metadata
  • derived stats and top-K projection
  • fenced shard ownership
• reads:
  • authoritative tag listing from assignment index
  • top-K from derived projection
  • content display from normalized references or hydration cache

Polished interview answer #

I’d design the unified tagging system as a shared metadata service with one authoritative tag and assignment store across Jira, Confluence, and Bitbucket. The core truth is a TagAssignment edge between a normalized content_ref and a shared tag_id, plus shared TagDefinition metadata. Adding or removing a tag is a guarded transition on that edge, clicking a tag reads the tag-to-content index across all products, and top-K popular tags is a derived projection built from maintained TagStats rather than a live full scan. The main scaling levers are sharding by tenant and tag, caching normalized content references, and maintaining popularity incrementally rather than recomputing it from scratch.

Concrete Substrate #

I’ll choose a shared tagging service with authoritative tag/assignment storage plus derived popularity views as the concrete baseline, because it matches the mechanics we derived:

• shared tag metadata
• guarded tag-assignment lifecycle
• derived stats and top-K
• one owner per shard

Concrete tech family:

• service in Go, Java, or Kotlin
• authoritative state store:
  • replicated relational DB or RocksDB-backed service state
• metadata/control:
  • internal shard routing or a small strongly consistent metadata layer
• optional indexing/search layer for tag listing acceleration

Each shard owner stores:

• TagDefinition
• TagAssignment
• TagStats
• ContentReference cache or normalized reference table

Derived layer stores:

• PopularTagsView

Operation Layer #

1. Add tag to content #

API

• AddTag(content_ref, tag_input, actor, request_id?)

Initiator

• user

Entry point

• tagging API

Authoritative decider

• shard owner for tenant/tag scope

Precondition

• content exists or is valid
• actor authorized to tag that content
• current assignment edge is addable

Transition

• create or resolve TagDefinition
• set TagAssignment(tag_id, content_ref) -> ACTIVE
• update TagStats

Response

• {tag_id, assignment_state}

2. Remove tag from content #

API

• RemoveTag(content_ref, tag_id, actor, expected_version?)

Initiator

• user

Entry point

• tagging API

Authoritative decider

• shard owner for tenant/tag scope

Precondition

• assignment edge currently active
• actor authorized

Transition

• set TagAssignment -> REMOVED
• decrement or recompute TagStats

Response

• {removed: true}

3. List items by tag #

API

• ListItemsByTag(tag_id_or_name, filters, cursor, limit)

Initiator

• user

Entry point

• tagging query API

Authoritative decider

• assignment index / shard owner

Precondition

• tag exists

Transition

• none

Response

• paginated content refs plus display metadata

4. Get top K popular tags #

API

• GetTopTags(k, filters?)

Initiator

• user

Entry point

• dashboard/query API

Authoritative decider

• popularity projection

Precondition

• none

Transition

• none

Response

• ranked tags with counts

5. Update tag metadata #

API

• UpdateTag(tag_id, patch, expected_version?)

Initiator

• user/admin

Entry point

• tagging API

Authoritative decider

• shard owner for tag scope

Precondition

• tag exists
• actor authorized

Transition

• overwrite TagDefinition

Entry Point vs Decider vs Responder #

Concrete HLD #

Main components:

• tagging write API
  • handles add/remove/update operations
• tag shard owners
  • authoritative owners of tag definitions, assignments, and stats
• tagging query API
  • handles list-by-tag and top-K reads
• content-reference normalization layer
  • stores or hydrates display metadata for Jira/Confluence/Bitbucket objects
• popularity projection
  • maintains ranked top-K views
• metadata/control service
  • tracks shard ownership and routing

Short Interview Version #

I’d design the unified tagging system as a shared metadata service with one authoritative tag and assignment store across Jira, Confluence, and Bitbucket. The core truth is a TagAssignment edge between a normalized content_ref and a shared tag_id, plus shared TagDefinition metadata. Adding or removing a tag is a guarded transition on that edge, clicking a tag reads the tag-to-content index across all products, and top-K popular tags is a derived projection built from maintained TagStats rather than a live full scan. The main scaling levers are sharding by tenant and tag, caching normalized content references, and maintaining popularity incrementally rather than recomputing it from scratch.