# Atlassian's LLD bank — researched requirements

**Researched:** 2026-08-18
**Why:** the user asked to *"read high quality sources online and replicate their best bits rather than
doing everything from scratch."* These four problems are Atlassian's recycled Code Design bank, so they
are less standardised than parking-lot and the research is worth more, not less.

## How to use this, and how not to

**Use it for requirements, edge cases and the scale-up ladder.** Those are facts about what interviews
probe, and they are exactly where our corpus is weakest — the one unresolved risk named in
`docs/specs/2026-08-18-deterministic-contract.md` is a test asserting a rule a competent candidate would
read differently. Research closes that.

**Do not copy published code.** Write the Java ourselves. Two reasons: licensing, and quality — a lot of
published LLD code optimises for looking clever in a blog post. The `logger` research is the clear case:
several sources make `Logger` a singleton, which is untestable and cannot be constructed twice with
different appenders. We reject it and keep it as a *defence question* instead.

**Public sources give us nothing for the parts that actually cost time** — contract-first structure,
measured diff budgets, the acceptance mirror. Nobody publishes those. Realistic saving: 20–30% per
problem, and a real gain in requirement completeness.

---

## The confirmed Atlassian discriminator

Repeated across sources, and it validates the Phase 4 design:

> Candidates with negative feedback often *do* solve the problem, but they **do not validate edge cases**
> or they **rewrite large portions of the code when a scale-up is introduced**. Atlassian expects designs
> where a scale-up requires minimal changes if the initial design is strong.

So for all four: the curveball ladder is the point, and the base problem is deliberately easy.

---

## 1 · Cost Explorer

Plans **BASIC / STANDARD / PREMIUM**. Monthly billing, yearly projection, **prorated adjustments** on a
mid-term upgrade or cancellation, and trial periods as an extension.

Worked example from the sources: BASIC at $9.99/month → yearly cost **$119.88**. Upgrading mid-year to
PREMIUM adjusts the remaining months.

**Design centre:** a pricing/plan policy seam. **Ambiguities that must be pinned in javadoc:** whether a
partial month is prorated by day or charged whole; whether an upgrade is charged immediately or at the
next cycle; whether a trial converts automatically; the rounding rule on a prorated amount (integer minor
units, and who absorbs the remainder).

**Sources:** [Atlassian LLD questions from recent interviews](https://medium.com/@prashant558908/atlassian-low-level-design-questions-from-recent-interviews-d09c463c0889), [Get SDE Ready](https://getsdeready.com/interview/atlassian/)

## 2 · Middleware Router

The most concrete of the four. An **in-memory router** storing path patterns mapped to a result (a handler
or a server id). A request path returns the **best matching** route.

Pattern kinds, with precise semantics:
- **Static** segments — `/foo/baz`
- **Wildcard `*`** matching **exactly one** segment — `/bar/*/baz` matches `/bar/a/baz` and `/bar/123/baz`
  but **not** `/bar/a/b/c/baz`
- **Path parameter `:name`** matching exactly one segment and **capturing** its value — `/users/:id`

**Design centre:** precedence. Static beats parameter beats wildcard; catch-all must be last. A **trie**
(`RouteNode`) is the natural structure. **Ambiguities to pin:** the precedence order itself, what happens
when two patterns tie, whether a trailing slash matters, whether matching is case-sensitive, what an
unmatched path returns (empty vs throw), and whether registering a duplicate pattern replaces or throws.

**Sources:** [Atlassian OOD — design a middleware router](https://leetcode.com/discuss/interview-question/object-oriented-design/2167390/atlassian-ood-design-a-middelware-router/), [URL Router LLD](https://medium.com/@choudharys710/lld-machine-coding-with-implementation-url-router-2f1ed481d132)

## 3 · Customer Satisfaction

A support ticketing system where customers rate an agent **out of 5**. The requirement *ladder* is
reported explicitly, and it maps almost exactly onto a base suite plus three curveballs:

1. Record a rating; list all agents with their average, **ordered highest first**
2. **Tie handling** when two agents share an average — the sources note there are several defensible
   options, which makes it a genuine ambiguity to decide and state
3. **Best agents per month**
4. **Export** each agent's monthly averages as **CSV, JSON or XML**

**Design centre:** the export-format seam plus month bucketing (so the clock must be injected).

**Sources:** [Atlassian LLD questions from recent interviews](https://medium.com/@prashant558908/atlassian-low-level-design-questions-from-recent-interviews-d09c463c0889)

## 4 · Rating System

Each agent receives **1–5** ratings, maintains a **running average**, and agents are returned **sorted by
average**, with **top-N**. Same scale-up expectation as above.

**Design centre:** the storage/ordering decision — an incrementally maintained average versus recompute,
and where the ordering policy lives.

**Sources:** [Atlassian Interview Experience, SWE India P40](https://leetcode.com/discuss/post/7412653/atlassian-interview-experience-swe-india-rhrg/), [Low Level Design Interviews](https://gagan93.me/blog/2024/05/17/low-level-design-interviews.html)

---

## The duplication problem, and the decision

**`customer-satisfaction` and `rating-system` are the same question in Atlassian's bank.** Both reduce to
"agents get 1–5 ratings, keep an average, return them sorted." The reports describe them almost
identically.

Authoring two near-identical problems would waste effort and inflate the corpus without adding value. But
deleting one is also wrong, because **Atlassian genuinely recycles this shape**, and meeting it twice with
different scale-ups is good preparation rather than repetition.

**Decision: keep both, and split them along different axes deliberately.**

| Problem | Axis it owns | Curveballs pull on |
|---|---|---|
| `rating-system` | **Storage and ordering.** Running average vs recompute; where the ordering policy lives; top-N | Tie-breaking policy · a weighted average that ages old ratings · top-N per category |
| `customer-satisfaction` (sealed) | **Reporting and format.** Month bucketing via an injected clock; the export-format seam | CSV/JSON/XML export · per-month best agent · a rating window that excludes ratings older than N days |

Neither may claim the other's axis. `rating-system` must not grow an exporter; `customer-satisfaction`
must not make top-N its centre. Each `DECISION_LOG.md` should state which axis it owns and name the other
problem, so a candidate meeting the second one recognises the shape and sees the different question.

**If the calendar tightens, `rating-system` is the one to cut** — `customer-satisfaction` is sealed, so it
is needed for the Phase 7 reserve, and it carries the richer, better-documented requirement ladder.
