My Team (manager drilldown): GitHub tickets

Overview

What we're building. A "My Team" page where a manager sees their team as an expandable tree. At first it shows only one page of their direct reports, with names and nothing else, so it opens fast. Opening a person shows the first page of the people who report to them, and a "Show more" row at the end loads the next page when there are many. The extra details, such as team size and signals like "top recognizer", load a moment later, in small groups for the people currently on screen, and are always calculated from live data. Anything that has to look at someone's whole team at once (filtering by a signal, searching by text, or showing a manager's team activity in the side panel) runs only when the manager asks for it, never automatically when the page loads, a row opens or the side panel opens.

How the work is organized. The work is split into tracks, not people. Tickets within a track mostly go in order. Different tracks can run at the same time whenever someone is free to pick them up. Backend and frontend tracks are kept separate. Each ticket ID starts with its track's letter. Tracks are listed in the order work flows between them, and tickets within a milestone follow the same order.

Track	Side	What it covers	Tickets
S. Shared	Everyone	The final scale and acceptance pass.	S1
C. Team calculations	Backend	The service interface, scoped live queries, batched calculations, request limits, and performance measurement.	C1–C5
P. Page plumbing	Backend	Feature flag, routes, the "who can see whom" check, and the endpoints that feed the table and the side panel.	P1–P6
G. Golditable	Frontend	General-purpose additions to the shared table: new controls and expandable rows.	G1–G2
U. My Team UI	Frontend	The page, its rows, the side panel, and mobile.	U1–U5

How the tracks connect. C feeds P through one interface (C1), so the endpoints never see how team data is calculated. P feeds both frontend tracks, so the frontend only touches the backend through P. G feeds U. The data format defines what P returns, and S1 checks everything at the end.

Business rules.

Only delivered peer-to-peer recognition counts, including private recognition. Anniversaries and nominations never count, and cross-company recognition is ignored because it is not permitted (D7).
A 12 month range is 365 days, and every range includes today up to now (D8).
The latest login is last_login_at (D8).
People under a disabled manager are treated as having no manager, so they do not appear. The page covers managers and their direct reports (D10).

How views get built. When a backend ticket serves a view, it ships a plain ERB with all the data in variables. The matching frontend ticket then makes it look and work right.

Calculation model. Asynchronous loading means separate browser requests, not jobs or precalculation. No new analytics tables, server-side result cache, rebuild scheduler, or event listener are required.

All operations use C1's service: paged children, batched row metadata, whole-subtree search/filtering, personal activity, and explicitly requested team activity.
Metadata requests coalesce displayed person IDs. Neither HTTP requests nor report-query sequences run once per person.
Initial loading does not calculate every tab count or the viewer's whole-team activity. A selected filter calculates its matching set and exact count before pagination.
Rows, metadata, and filtered results have explicit context, loading, freshness, and error semantics.
C5 measures query cost and concurrency early. Query count alone does not establish performance.

If live queries exceed the budget after scoped query/index tuning, a separate optimization can introduce caching or materialized facts behind the same contract. The architecture describes those extensions; they are not dependencies of the tasks below.

Data format

This page fixes the format between the backend and the frontend, so both can build in parallel. Golditable already follows the published DataTables format (paging, recordsTotal, recordsFiltered, DT_RowId and DT_RowAttr), so the only decisions here are the attributes specific to "My Team". The placeholder endpoints in P1 return exactly this, and if a field needs to change, change it here first.

Endpoints

Every endpoint the page calls, what triggers it and what comes back. Row numbers are always their own request.

GET /manager/team: the page shell as HTML, and the table's rows as JSON when Golditable asks for them. Besides Golditable's usual paging params, it takes status (all, invite_pending, stale, gaps or top_recognizers) and search_term. With status=all and no search, rows are the viewer's direct reports; otherwise they are flat full-subtree results. Served by P3 and P5.
GET /manager/team/children?parent_id=42&cursor=: one page of one person's child identities, with a parent ID, expansion information, metadata placeholders and the next cursor. The first request has no cursor; "Show more" sends the one it was given (D11). Served by P4.
GET /manager/team/metadata?user_ids=42,57: calculated row metadata for a capped/deduplicated batch, keyed by person ID and bound to the active context. Served by P5.
GET /manager/team_members/:id: personal facts/activity for the side panel, without team-wide aggregation. Its period is independent of the table. Served by P6.
GET /manager/team_members/:id/team_activity: explicit manager/team metrics and paged member lists. Served by P6.

Rules for every endpoint

ManagerAdmin::TeamDataset (C1) returns plain data structs, defined in the architecture. The endpoints (P3 and P4) convert those structs into the table's JSON. The first column of each row (the person's name, the expand arrow, who they report to, and the count placeholders) is sent as a snippet of HTML, in the member field of the row example below. The service itself never produces HTML or table-specific fields.

Date range. Requests that calculate numbers (metadata, filters and team activity) take one of three presets: 30d, 90d or 12m. The server turns the preset into exact start and end times, and every request for the same view uses the same dates, so rows and numbers always agree.
Sorting and paging. Lists of people are paged and can be sorted by name, A to Z (name_asc) or Z to A (name_desc). The top level pages with Golditable's start and length. The page size is 25 by default and comes from the team_page_size InternalSetting (D11). Groups opened under a person page by cursor instead (D11).
Access. Any request that names a person (a row's children, a metadata batch, the side panel) first checks, on live data, that the person is in the viewer's team (P2). A metadata batch checks every ID in it.

Table response

The table's JSON response:

{
  "recordsTotal": 12,
  "recordsFiltered": 12,
  "data": [ …rows… ],
  "context_key": "view-request-42",
  "consistency": "live",
  "tab_data_counts": {},
  "tab_data_labels": { "stale": "No recognition 90d+" },
  "has_more": false
}

Each identity row, in the table and child-page responses:

{
  "DT_RowId": "team-row-42",
  "DT_RowAttr": { "data-node-id": 42, "data-parent-id": 7, "data-depth": 1, "data-has-children": true },
  "member": "<HTML: identity, expansion control, manager context, and count placeholders>",
  "metadata_state": "pending",
  "last_from_manager": "<HTML: loading placeholder>",
  "signals": "<HTML: loading placeholder>"
}

Child pages use the same paging envelope with parent_id, plus a next_cursor that is null on the last page (D11). Metadata has a separate envelope:

{
  "context_key": "view-request-42",
  "consistency": "live",
  "calculated_at": "<ISO timestamp>",
  "metadata": { "42": { "state": "ready", "manager_id": 7, "stale": true, "…": "…" } }
}

Counts, loading and errors

tab_data_counts contains only known unsearched filter counts for the current context. Initial loading leaves it empty. Unknown badges are omitted, not zero.
Ready filtered results contain exact recordsFiltered after full-subtree filtering and before pagination. Text-search counts do not overwrite unsearched tab badges.
Loading is represented while a request is in flight. Failed queries/metadata are errors, not successful empty rows or zero values.
The same resolved period must be used by identity and metadata requests. Context keys do not grant access or imply a database snapshot.

Milestones

A milestone is a point where part of the feature works end to end on real data, behind the flag. Milestones aren't sprints. Each sprint, pull the next tickets from each track toward the next milestone, as far as capacity allows. M1 is small enough for part of a sprint.

M5 starts as soon as C3 and C4 are available and runs alongside panel work. Query qualification is not postponed until UI completion.

Milestone	What works at the end	Tickets
M1. Foundations	With the flag on, "My Team" shows placeholder data in Golditable, with the date range dropdown.	C1, P1, G1
M2. Team identities	Paged direct reports, individual expansion/collapse with a "Show more" row for wide groups, name search, and sibling sort. Calculated counts/signals have placeholders.	C2, P2, P3, P4, G2, U1
M3. Live metadata and filters	Bounded metadata batches fill counts/signals; selected whole-team filters return exact paged results and counts.	C3, C4, P5, U2
M4. Side panel	Personal activity loads independently; team activity/member lists load explicitly. The panel closes and reopens.	P6, U3, U4
M5. Query qualification	Initial, metadata, filter, and team-activity requests are measured separately, including cold queries and concurrency.	C5
M6. Ready to launch	Tablet and phone layouts, and the acceptance pass.	S1, U5

M3 needs the identity/scoping foundation. Real panel calculations need C3, while panel presentation can use fixtures earlier. M5 uses the instrumented calculations from M3.

What the existing POC branch tells us

The proof-of-concept branch zach/11074/manager-drilldown is a visual/reference implementation, not the data contract.
Existing direct-report loading in users/index.js demonstrates on-demand fetching and browser reuse. Its spanning detail containers are not a hierarchy-aware treegrid model.
Use existing eligibility and recognition scopes, with the policy and grain checks in the architecture. The full source report/helper must not run once per displayed user.
Generic Golditable additions are opt-in. Existing tables retain their behavior.

Shared

S1. Test at scale and check the acceptance criteria

Context: Initial rows, metadata, filters, and team activity have different cost profiles. Verify each on representative data and check the product acceptance criteria.

Outcome: The feature is shown to hold up on a large org and to meet the spec's acceptance criteria.

Acceptance criteria:

Test forests include 84,611 people at depth 12, smaller deep trees, wide sibling groups, and high recognition fan-out.
Measure initial rows, metadata batches, filter queries, explicit team activity, and rendering independently under concurrent load.
Set final row/ID/concurrency/rendering limits from the measurements.
Verify no automatic all-tab-count or team-activity operation is triggered by initial loading. Row metadata may still require the broader source scopes documented in the architecture.
Feature specs cover the spec's acceptance criteria.

Implementation notes:

Use the production timings recorded in C5 alongside the test org's.

Waits on: everything else, and C5 for the production timings.

Track C: team calculations (backend)

C1. Core TeamDataset class

Context: Every read of team data (rows, metadata, filters and the side panel) goes through one typed, scoped service, the TeamDataset class. Hierarchy rows (who reports to whom) load without calculated metadata such as counts and signals, which arrive in a separate request. The counts and signals for the rows on screen load automatically, in a bounded batch, right after the page loads and after each row opens. Whole-team operations (signal filters, text search and team activity) are different: they look at someone's whole team, so they run only when someone asks for them, never on page load, row expansion or opening the side panel.

Outcome: There is one interface for "My Team"'s data, with a fixed input and output, plus the test helpers to build on it.

Acceptance criteria:

ManagerAdmin::TeamDataset exposes children, metadata, search, person, and team_activity, as specified in the architecture.
Child responses contain only a page of identities, parent/depth/expansion fields, and metadata placeholders.
Child responses include a cursor for the next page, or none on the last page (D11).
Metadata accepts a bounded ID batch and returns row counts/signals keyed by ID.
Search/filter results cover the authorized subtree before paging and include an exact result count, not every tab's aggregate.
Personal and team activity are separate operations. All results carry appropriate scope, range, calculation time, and context.
Results are plain objects (for example Data structs), not ActiveRecord models, so callers can't query through them.
Shared examples check the result for a known multi-level team, so any later implementation runs against the same specs.
A test factory builds a multi-level team. Today's factories only build one level.
A test helper builds results directly, so endpoint specs can run before the calculations exist (C2, C3).

Implementation notes:

Field definitions are independent of storage or controller rendering.
The page size is read in one place, TeamDataset.page_size. It comes from the team_page_size InternalSetting, defaults to 25 when the setting is missing or invalid, and is capped at 50 (D11).
children takes an offset for the top level (Golditable's numbered pager) and a cursor for expanded groups. Callers use one or the other (D11).
Periods resolve centrally to company-local dates and UTC query bounds. 12m is 365 days, and every range ends now, including today (D8).
Place the facade and required helpers under app/services/manager_admin/. No provider framework or persisted analytics models are required.

Sketch:

Every endpoint reads team data through one service. The dashed outline is what this ticket builds.

Proposed code (a sketch of the shape, not final):

# app/services/manager_admin/team_dataset.rb
module ManagerAdmin
  class TeamDataset
    PERIODS = %w[30d 90d 12m].freeze                         # D8: defined once, here; 12m means 365 days
    TOP_RECOGNIZER_MIN = { "30d" => 4, "90d" => 13, "12m" => 52 }.freeze

    DEFAULT_PAGE_SIZE = 25
    MAX_PAGE_SIZE     = 50                                   # hard cap, whatever the setting says

    # Rows per page, changeable without a deploy: InternalSetting key `team_page_size`
    def self.page_size
      configured = InternalSetting.find_by(key: "team_page_size")&.value.to_i   # missing or junk => 0
      configured.positive? ? [configured, MAX_PAGE_SIZE].min : DEFAULT_PAGE_SIZE
    end

    Row  = Data.define(:id, :manager_id, :parent_id, :depth, :name,
                       :has_children, :invite_pending)
    Meta = Data.define(:id, :manager_id, :direct_count, :descendant_count,
                       :last_recognition_from_manager_at, :stale,
                       :top_recognizer, :stale_direct_count)
    Page = Data.define(:rows, :records_total, :records_filtered, :has_more,
                       :next_cursor, :context)   # next_cursor is nil on the last page

    def initialize(viewer:, period:); end

    # offset pages the top level (Golditable's pager); cursor pages an expanded group (D11)
    def children(parent_id:, limit:, sort:, offset: nil, cursor: nil); end   # => Page of Row
    def metadata(user_ids:); end                             # => { id => Meta }
    def search(query:, filter:, offset:, limit:, sort:); end # => Page of Row, exact count
    def person(user_id:); end                                # personal activity only
    def team_activity(user_id:, offset:, limit:); end        # explicit, paged
  end
end

Callers (how clients use it):

# How clients call it: one dataset per request, then the method that matches the action
dataset = ManagerAdmin::TeamDataset.new(viewer: current_user, period: params[:period] || "90d")

# Table: cheap, bounded by page size
dataset.children(parent_id: viewer.id, offset: 0, limit: 25, sort: "name")  # P3: top level, numbered pager
dataset.children(parent_id: id, cursor: nil, limit: 25, sort: "name")       # P4: first page of a group
dataset.children(parent_id: id, cursor: page.next_cursor, limit: 25, sort: "name")  # P4: "Show more"
dataset.metadata(user_ids: visible_ids)                               # P5: one batch for the rows on screen (max 50)

# Side panel: personal first, team only when asked
dataset.person(user_id: id)                                           # P6: on open
dataset.team_activity(user_id: id, offset: 0, limit: 25)              # P6: explicit request only

# Whole-subtree work: only on an explicit user action, never on load, expand or panel open
dataset.search(query: "ana", filter: "stale", offset: 0, limit: 25, sort: "name")   # P5

# Rules for every caller
#   - never one metadata call per row; pass the visible ids
#   - never rescue errors into zero or empty (C4)
#   - keep one period per view, so rows and signals agree
#   - treat results as read-only values

Waits on: nothing.

C2. Query child identities and hierarchy scope

Context: Normal navigation needs a page of one person's direct reports, not a whole-company report. Subtree discovery is required only by explicitly broader operations.

Outcome: The service returns bounded, authorized identity rows and reusable live hierarchy helpers.

Acceptance criteria:

The initial request returns only the viewer's direct-report page, including pending invites and excluding disabled users.
Anyone below a disabled manager is treated as having no manager and is not returned (D10).
Each child request returns only one parent's next page, found by a cursor holding the sort value and ID of the last row seen, and says whether more remain (D11).
A person who moves, is added or is disabled between two clicks never causes a repeated or missing row in a group.
Identity, manager/depth, pending status, and has_children are correct without recognition aggregation.
Direct/descendant totals are metadata, not a prerequisite for identity rows.
Subtree helpers support search, descendant counts, and full-scope filters without being called by every identity request.
Loops in the manager chain don't break it or list anyone twice.
There is no per-user association-query loop. Batched ancestor traversal can scale with depth; bulk parameter limits may require chunking.
It passes C1's shared examples for the tree fields.

Implementation notes:

Use scoped ActiveRecord relations for paged children and batched/indexed child existence checks. Order by the sort key and then ID, and fetch one extra row to know whether more remain. Offsets are used only for the top level.
When a broader operation needs hierarchy data, load scalar columns and calculate counts in one bottom-up pass, reusing the index within that operation.
Do not materialize the full organization on every expansion or copy descendant arrays for every manager.

Sketch:

A child page returns only identity fields. Counts and signals arrive later, from the metadata request.

Proposed code (a sketch of the shape, not final):

def children(parent_id:, limit:, sort:, offset: nil, cursor: nil)
  authorize_targets!([parent_id])                      # P2: live access check
  scope = company.users.not_disabled                   # keeps pending invites
                 .where(manager_id: parent_id)
  ordered = scope.order(sort_sql(sort), :id)           # sort key first, ID breaks ties (D11)

  rows =
    if cursor                                          # expanded group: keyset paging
      ordered.after_cursor(cursor, sort).limit(limit + 1)   # one extra row says whether more remain
    else                                               # top level: Golditable's numbered pager
      ordered.offset(offset.to_i).limit(limit + 1)
    end.pluck(:id, :manager_id, :name)                 # scalar columns, no models

  more = rows.size > limit
  rows = rows.first(limit)

  # one query for every row on the page, not one per row
  with_children = company.users.not_disabled
                         .where(manager_id: rows.map(&:first))
                         .distinct.pluck(:manager_id).to_set

  Page.new(rows: rows.map { |id, mgr, name| build_row(id, mgr, name, with_children.include?(id)) },
           records_total: scope.count, records_filtered: scope.count,
           has_more: more,
           next_cursor: (more ? encode_cursor(rows.last, sort) : nil),   # sort value + ID of the last row
           context: context)
end

Waits on: C1.

C3. Calculate batched metadata and requested team metrics

Context: Displayed rows request metadata in batches. Signal filters and team activity require broader calculations, but run only when explicitly requested.

Outcome: Each operation calculates only its required facts, with correct row, direct-report, and descendant semantics.

Acceptance criteria:

A metadata batch returns last recognition from current manager, stale/top-recognizer flags, direct/descendant counts, and direct-report gaps for its requested IDs.
Metadata does not calculate all three periods or every person's panel activity.
Personal activity calculates its required sent/received/login facts; team activity calculates the requested manager's rollups and paged member lists.
Full-subtree signal filtering happens before paging. Unqueried tab counts are not automatically calculated.
Recognition counts only delivered peer-to-peer recognition: sent by a person, with successful recipients, and never anniversary or nomination recognition, and including private recognition (D7). Queries also use a distinct recipient grain, failure/deletion rules, and explicit thresholds (D8).
Counts and traversal skip people below a disabled manager, the same as access checks do (D10).
Query count is bounded by operation/query families and deliberate chunks, not a full report query sequence per person.
It passes C1's shared examples for the recognition fields.

Implementation notes:

Use existing visible, non_system, with_peer_badges, and recipient failure scopes as far as they match the policy above. Add filters for anniversary and nomination recognition if the existing scopes do not already exclude them. Check that visible does not drop private recognition, because the metrics must include it. Managers see counts and dates only, never the content of private recognition.
Group sent counts by sender, received counts by distinct recognition/person, and manager recognition by current manager/recipient pair. Do not multiply events through unrelated joins.
Work out "stale" as "no recognition from their current manager inside the range", not by comparing the last recognition with the range's start. Both give the same answer for ranges ending today, but only the first works for ranges that end in the past (D8).
"Signed in" uses last_login_at (D8).
Reuse hierarchy facts from C2 and aggregate only the requested direct/descendant scopes.

Sketch:

A metadata batch validates, checks access once, resolves the period, then queries each fact at its own grain. Whole-team work runs only on request.

Proposed code (a sketch of the shape, not final):

def metadata(user_ids:)
  ids   = authorize_targets!(user_ids)                 # one shared ancestor lookup
  range = resolve_period(period)                       # company-local days, ending now, 12m = 365 days (D8)

  # one query per fact, each at its own grain, then merge by person id
  # recognition = delivered peer-to-peer only: no system, anniversary or nomination; private included (D7)
  sent = visible_recognitions.where(sender_id: ids, created_at: range)
           .group(:sender_id).count                    # by sender, never multiplied by recipients

  from_manager = successful_recipients
           .joins(:recognition).joins(:user)
           .where(user_id: ids)
           .where("recognitions.sender_id = users.manager_id")   # current manager only
           .group(:user_id)

  last_ever = from_manager.maximum("recognitions.created_at")     # all-time, not cut to 12 months
  in_range  = from_manager.where(recognitions: { created_at: range }).distinct.pluck(:user_id).to_set

  ids.index_with do |id|
    Meta.new(id: id, last_recognition_from_manager_at: last_ever[id],
             stale: !in_range.include?(id),            # "none inside the range"
             top_recognizer: sent.fetch(id, 0) >= TOP_RECOGNIZER_MIN.fetch(period), **hierarchy_counts(id))
  end
end

Waits on: C2.

C4. Enforce request bounds, context, and observability

Context: Asynchronous metadata can create excessive concurrency unless requests are batched and bounded. Live data can also change between identity and metadata reads.

Outcome: Requests reject oversized/invalid inputs, identify their calculation context, and expose useful performance diagnostics.

Acceptance criteria:

Metadata ID lists are capped, validated, and deduplicated; page/list sizes have server-enforced limits.
Responses identify resolved range, policy, context, and query/calculation time without pretending to be a shared snapshot.
Metadata includes current manager identity so obsolete branch positions can be detected.
Errors/timeouts are surfaced explicitly; no zero/false/empty success fallback is returned.
Log operation type, requested population, source/query cost where available, duration, and output size without logging personal payloads.
No Rails.cache report wrapper, scheduled rebuild, or calculation job is introduced.

Implementation notes:

Put request limits and normalized context at the service boundary.
Browser coalescing, one or two concurrent metadata requests, and stale-response protection are implemented by U2; server limits remain independent of the client.

Proposed code (a sketch of the shape, not final):

MAX_IDS = 50                                           # tuned in C5

def validate_ids!(raw)
  ids = raw.to_s.split(",").map(&:to_i).uniq           # dedupe
  raise ActionController::BadRequest, "too many ids" if ids.size > MAX_IDS
  ids
end

def timed(operation, population)
  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  result = yield
  ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
  Rails.logger.info(operation: operation, population: population, ms: ms)  # no personal data
  [result, ms]
end

# Errors and timeouts are raised and reported. Nothing rescues them into zero, false or empty.

Waits on: C2.

C5. Measure on production data and decide

Context: Production hierarchy sizes are known, including an 84,611-person forest, but recognition volume, fan-out, and live-query latency require measurement. Asynchronous requests alone do not establish scalability.

Outcome: We know how fast live calculation is on production data, and have decided whether it's enough (D9).

Acceptance criteria:

Measure initial identities, metadata batches, whole-team filters, and explicit team activity separately for each preset and under concurrent load.
Include wide direct-report groups, deep forests, large recipient fan-out, and rows whose descendant totals span much of the company.
Recommend the limit on rendered rows for "Show more" (D11), based on how the page behaves with a wide group fully expanded.
Compare with the architecture's initial targets: 500 ms identity pages, 1 second metadata batches, and 2 seconds requested filters/team activity, measured at p95.
Tune query scope, indexes, batching, and concurrency first. Any server cache or persisted analytics is a separately justified optimization with scope/freshness requirements.
The timings are recorded for S1.

Implementation notes:

Run against production data without loading the primary database, for example on a read replica or by running the generated SQL there.
C4's timing logs from companies already using the flag add real-world numbers.
Everything goes through C1's interface and tests check output, so tuning or replacing the calculation doesn't touch the endpoints.

Waits on: C3, C4.

Track P: page plumbing (backend)

P1. Add the feature flag, routes and placeholder endpoints

Context: "My Team" is a new Manager Portal page that replaces the existing Direct Reports page, and it ships behind a feature flag. This ticket adds the flag, routes and controllers. Endpoints return fake data first, so frontend work can start before real data exists (the Data format page defines the format).

Outcome: "My Team" sits behind the manager_team_tree flag, and its endpoints return placeholder data so frontend work isn't blocked.

Acceptance criteria:

Flag off: every "My Team" URL returns 404, and Direct Reports is unchanged.
Flag on: the sidebar shows "My Team" in place of Direct Reports, and the Direct Reports URL redirects.
Each endpoint returns fixture data in the format on the Data format page until its live implementation is wired.
Tests: controller specs.

Implementation notes:

Create the manager_team_tree flag, and add the new controllers, routes and permission rules.
Start from: config/feature_flags.yml, ManagerAdmin::BaseController, config/routes/company/manager_admin_routes.rb, _manager_admin_sidebar.html.erb:9, the manager block of config/authorization_rules.rb.

Sketch:

With the flag off nothing changes. With it on, "My Team" replaces Direct Reports in the sidebar.

Proposed code (a sketch of the shape, not final):

# config/routes/company/manager_admin_routes.rb
get "team",          to: "team#index"
get "team/children", to: "team#children"
get "team/metadata", to: "team#metadata"
resources :team_members, only: :show do
  member do
    get :team_activity
  end
end

class ManagerAdmin::TeamController < ManagerAdmin::BaseController
  before_action { head :not_found unless flag_enabled?(:manager_team_tree) }  # flag off: 404

  def index
    respond_to do |format|
      format.html
      format.json { render json: TeamFixtures.table_page }   # placeholders in the Data format
    end
  end
end

Waits on: nothing. The placeholder data follows the Data format page.

P2. Block access to people outside the manager's team

Context: Child, metadata, personal, and team-activity operations must validate current reporting scope. A previously loaded browser row does not authorize another request.

Outcome: Nobody outside a manager's team can be reached through any endpoint.

Acceptance criteria:

One shared check validates company, eligibility, and current reporting scope. A disabled manager breaks the chain, so people below one are not reachable (D10).
Every person-ID endpoint and metadata batch uses it and returns the standard unavailable/not-found response on failure.
The viewer is allowed as the root for initial children and their own personal/team activity, but is excluded from descendant listings.
Disabled/deleted/out-of-scope targets are refused even if an old browser row still exists.
Batched targets share ancestor lookups; there is no separate full chain traversal per ID.
Tests: controller specs.

Implementation notes:

Apply cycle-safe live ancestry validation and company scope. Existing manager-chain helpers illustrate cycle handling but must not be called independently for every metadata target.

Sketch:

Anyone a manager can open is themselves or below them. Everyone else returns 404: above, beside, disabled or in another company.

Proposed code (a sketch of the shape, not final):

def authorize_targets!(ids)
  targets  = ids.uniq - [viewer.id]
  climbing = targets.index_with { |id| id }              # target => node we are climbing from
  seen, found = Set.new, Set.new

  # climb every target's manager chain together: one query per level, not per person
  while climbing.any?
    managers = company.users.not_disabled
                      .where(id: climbing.values.uniq).pluck(:id, :manager_id).to_h
    climbing = climbing.filter_map do |target, node|
      boss = managers[node]
      next if boss.nil?                                  # reached a root: not under the viewer
      (found << target) && next if boss == viewer.id
      [target, boss] if seen.add?([target, boss])        # cycle guard
    end.to_h
  end

  raise ActiveRecord::RecordNotFound unless found.size == targets.size   # standard 404
  ids
end

Waits on: P1.

P3. Serve the tree's top level

Context: The "My Team" table first shows the manager's direct reports, and people expand to reveal their own reports, which makes the tree. This endpoint serves that top level to Golditable (the app's shared table component), one page at a time. Its data comes from the team data interface (C1). The POC (the proof-of-concept branch zach/11074/manager-drilldown) has a datatable to start from.

Outcome: The main "My Team" table endpoint returns the manager's direct reports (the tree's top level), read through the team data interface.

Acceptance criteria:

It returns the manager's direct reports, one page at a time. The page size is 25 unless the team_page_size InternalSetting says otherwise, and the table's pager uses the same size (D11).
Identity and expansion fields arrive without recognition or full-subtree aggregation; counts/signals are placeholders until metadata is requested.
When a search is active, it returns a flat list instead, with "Reports to …" on each person.
Search covers name, display name and email. Sort is A→Z / Z→A.
All team data comes through the team data interface (C1).
Tests: controller specs.

Implementation notes:

Start from: the POC's team_tree_datatable.rb. It reads the POC's TeamTree directly; read through C1's interface instead.

Sketch:

The same endpoint returns two shapes: the top level of the tree, or a flat list when a tab or search is active.

Waits on: P1, C1 (test data until C2 lands).

P4. Serve one person's child page

Context: Expanding one row fetches one person's direct reports. Child metadata is a separate bounded request.

Outcome: The tree can retrieve the next child identity page for one authorized parent.

Acceptance criteria:

GET /manager/team/children?parent_id= returns one page of identities (the configured page size, 25 by default), parent context, the group's total, a next cursor, and metadata placeholders.
Adding &cursor= returns the page after that cursor. The last page has no next cursor (D11).
The endpoint does not recursively load descendants or calculate recognition metadata.
No subtree or unbounded multi-parent endpoint is introduced.
All reads go through C1's service and P2's authorization.
Tests: controller specs.

Implementation notes:

Use the same row format as P3 for a single requested parent, but page by cursor instead of offset. The cursor is opaque to the browser, which only sends back what it was given.

Sketch:

Expanding a row requests one parent's next page. Its children stay collapsed until clicked.

Proposed code (a sketch of the shape, not final):

def children
  parent_id = params.require(:parent_id).to_i
  authorize_targets!([parent_id]) unless parent_id == current_user.id   # P2

  page = dataset.children(parent_id: parent_id, cursor: params[:cursor],   # nil on the first page
                          limit: limit, sort: sort)
  render json: TeamRows.page(page)        # rows, group total, next_cursor (nil on the last page)
end

private

def limit = ManagerAdmin::TeamDataset.page_size         # InternalSetting, capped at 50; ignores the client's length

Waits on: P2, C1.

P5. Serve batched metadata and selected filters

Context: Row metadata and full-subtree filtering are separate live operations. Both use the selected period, but neither request automatically calculates every tab count. The metadata endpoint hydrates displayed rows; the table endpoint calculates selected filter membership.

Outcome: Displayed rows can load metadata independently, and selected filters return correctly paged full-subtree results.

Acceptance criteria:

GET /manager/team/metadata?user_ids= uses C3/C4 for bounded, authorized live calculation keyed by person ID.
Metadata errors do not become false/zero signals, and responses carry calculation time and current manager identity.
Tab labels reflect the period without triggering count queries.
Only requested filters calculate their matching set and exact count. Unknown badges remain absent; searched counts do not replace unsearched badges.
When a tab is active, a flat list of the people in it is returned, with "Reports to …" on each person.
Tests: controller specs.

Implementation notes:

Add the metadata endpoint and extend P3's table endpoint for status, period, and search. Do not automatically calculate all tab counts when either endpoint is called.

Sketch:

A selected tab returns a flat list with an exact count and no counts on other tabs. Row numbers arrive separately, in a metadata batch.

Proposed code (a sketch of the shape, not final):

def metadata
  ids = validate_ids!(params[:user_ids])                 # C4: cap and dedupe
  authorize_targets!(ids)                                # P2
  render json: TeamMetadata.envelope(dataset.metadata(user_ids: ids))
end

def index                                                # extends P3
  filtered = params[:status].present? && params[:status] != "all"
  page =
    if filtered || params[:search_term].present?
      dataset.search(query: params[:search_term], filter: params[:status],
                     offset: offset, limit: limit, sort: sort)   # whole subtree, before paging
    else
      dataset.children(parent_id: current_user.id, offset: offset, limit: limit, sort: sort)   # top level: offset
    end
  render json: TeamTable.json(page, tab_data_counts: {}) # never count the other tabs
end

Waits on: P2, P3, C3, C4.

P6. Serve the side panel

Context: Clicking a person in the table opens a side panel with details about them. This endpoint renders that panel as plain HTML, and the frontend ticket (U3) later makes it look right and work smoothly. Numbers come from the team data interface (C1). Live facts are looked up when the panel is requested. The POC (the proof-of-concept branch zach/11074/manager-drilldown) has a panel to use as a reference.

Outcome: Personal activity renders independently of a separate explicit team-activity request.

Acceptance criteria:

It combines numbers from the team data interface with live facts: last login (last_login_at), account status, and redeemable points (respecting the company's hide-points setting).
The default personal endpoint builds the authorized breadcrumb and personal facts, without descendant recognition aggregates or full member lists.
The team-activity endpoint calculates requested manager metrics and pages missed/pending/direct-report lists.
The viewer's initially open personal panel does not trigger team-activity queries.
Tests: controller specs.

Implementation notes:

Use the POC panel as a layout reference, but separate personal loading from the Load team activity action. Presets and range semantics follow D8.

Sketch:

The panel renders in two requests: personal facts first, and team activity only when the user asks for it.

Proposed code (a sketch of the shape, not final):

class ManagerAdmin::TeamMembersController < ManagerAdmin::BaseController
  before_action { authorize_targets!([target_id]) }      # P2, every action

  def show                                               # request 1: personal only
    @person = dataset.person(user_id: target_id)
  end

  def team_activity                                      # request 2: only when asked
    @activity = dataset.team_activity(user_id: target_id, offset: offset, limit: limit)
  end
end

Waits on: P2, C3, C4 for live behavior; presentation can begin against C1 fixtures.

Track G: Golditable (frontend)

Both tickets add general-purpose features that do nothing unless a table opts in. Existing Golditable pages, including nominations and campaigns, must retain their behavior.

G1. Add new controls to the controls bar

Context: Golditable (the app's shared table component) needs two small additions for "My Team": a date range dropdown in its controls bar, and tab labels that follow the chosen range (for example "No recognition 90d+"). The POC (the proof-of-concept branch zach/11074/manager-drilldown) already has these, so this is porting work.

Outcome: Golditable's controls bar supports a date range dropdown and tab labels that follow it.

Acceptance criteria:

A dropdown sits at the end of the controls bar (for the date range).
Tab labels update when the date range changes.
Count badges are optional. Missing counts are omitted, not converted to zero or fetched automatically.
The tab click handler is fixed.
Tabs keep the regular Golditable style (D1).
Tests: feature specs.

Implementation notes:

Port these from the POC.

Sketch:

A date range dropdown joins the end of the controls bar, and the tab label follows the chosen range.

Waits on: P1 (placeholder data).

G2. Make table rows expandable

Context: "My Team" shows people as a tree, where a manager's row expands to show their reports. Golditable (the app's shared table component) can't do expandable rows yet, so this adds them as an opt-in feature. The users page already loads direct reports on demand, and this builds on that idea. The POC (the proof-of-concept branch zach/11074/manager-drilldown) has related code to port.

Outcome: Golditable rows can expand in place to show a manager's reports, as an opt-in feature.

Acceptance criteria:

Clicking a manager loads one child page underneath and emits the newly displayed IDs for metadata hydration.
When a manager has more reports than one page, a "Show N more" row sits at the end of the group. Clicking it loads the next page by cursor, adds the rows above it, emits their IDs for metadata hydration, and moves focus to the first new row (D11).
Successfully loaded rows are reusable for collapse/re-expand within the current view. Changing page, sort, or search may reset expansion.
There are no Expand all or Collapse all toolbar controls.
A period change refreshes displayed metadata without eagerly loading hidden branches. An active signal filter reruns its membership query.
Once the table has a set number of rendered rows, "Show more" stops loading and tells the person to use search. The limit comes from C5's measurements.
A failed "Show more" shows a Retry that repeats the same cursor, and the rows already loaded stay.
Rows loaded through "Show more" are kept for collapse and re-expand. Group size and position are exposed to assistive technology (aria-setsize, aria-posinset).
Each person is a first-class row with shared columns; sorting preserves sibling groups rather than globally reordering the tree.
Keyboard navigation, expansion state, and focus on collapse are accessible.
Tests: feature specs.

Implementation notes:

Reuse the users-page idea of on-demand loading, not recursive nested detail containers or one DataTable/controller per manager.
The adapter must reconcile hierarchy ordering and per-parent paging with Golditable; native global sorting/paging of a flat set is not sufficient.
Golditable's pager only pages the top-level rows, and rows inserted under a parent live outside DataTables and are cleared on any redraw. That is why groups use a "Show more" row rather than a numbered pager (D11). The POC's approach of flattening the whole visible tree on the server and re-sending the expanded IDs on every draw is not used.
Build it as a Stimulus controller under app/frontend/controllers/, following the repo's JavaScript rules, with no inline script.
Use the service's parent IDs and a flattened visible-row representation. Keep presentation and request-context state separate from source data.

Sketch:

A row's children load on click. Loading, loaded and failed are separate states, and a failure can be retried.

Proposed code (a sketch of the shape, not final):

const MAX_RENDERED_ROWS = 500                         // set from C5's measurements (D11)
const loaded = new Map()                                 // parent id => { rows, nextCursor, total }

async function expand(row) {
  const id = row.dataset.nodeId
  if (!loaded.has(id)) {                                 // reuse on collapse and re-expand
    setState(row, "loading")
    try {
      const page = await fetchJson(`/manager/team/children?parent_id=${id}`)
      loaded.set(id, { rows: page.data, nextCursor: page.next_cursor, total: page.recordsTotal })
    } catch {
      return setState(row, "failed")                     // the Retry button calls expand(row) again
    }
  }
  const group = loaded.get(id)
  insertChildren(row, group.rows)                        // rows keep data-parent-id and data-depth
  if (group.nextCursor) insertShowMore(row, group)       // "Show 12 more" row after the last child
  hydrate(ids(group.rows))                               // U2's metadata queue
  setState(row, "expanded")
}

async function showMore(row, group) {                    // click on the "Show more" row
  if (renderedRowCount() >= MAX_RENDERED_ROWS) return showSearchHint(row)   // "Use search to narrow this down"
  setState(row, "loading")
  try {
    const url = `/manager/team/children?parent_id=${row.dataset.parentId}&cursor=${group.nextCursor}`
    const page = await fetchJson(url)                    // same sort, so the cursor stays valid
    group.rows.push(...page.data)
    group.nextCursor = page.next_cursor
    insertBeforeShowMore(row, page.data)                 // new rows go above the "Show more" row
    if (!page.next_cursor) removeShowMore(row)
    hydrate(ids(page.data))
    focusFirst(page.data)                                // keep the keyboard user's place
  } catch {
    setState(row, "failed")                              // Retry repeats the same cursor
  }
}

Waits on: P1 (placeholder data).

Track U: My Team UI (frontend)

U1. Build the "My Team" page and its tree rows

Context: This builds the "My Team" page itself on top of Golditable (the app's shared table component). It uses the placeholder data from P1 until the real endpoints land, and relies on G2 for expandable rows. The POC (the proof-of-concept branch zach/11074/manager-drilldown) has styles and markup to port.

Outcome: The "My Team" page shows the tree, with each row laid out as designed.

Acceptance criteria:

The page layout is built.
Identity rows show avatar/name/expansion information immediately and "Reports to …" in flat results.
"N direct · N total", last manager recognition, and signals have metadata placeholders rather than fabricated values.
The first table request loads only one direct-report page.
Tests: feature specs.

Implementation notes:

Start from: the POC's my_team.scss and _member_cell.html.erb. Swap their hard-coded colors for our design tokens.

Sketch:

The page layout: controls, tabs and tree rows, with placeholders where numbers will arrive. The side panel is U3.

Waits on: P1 (placeholder data), and G2 for expanding.

U2. Show the signals and filter tabs

Context: Signals are chips on each row that flag what needs a manager's attention. Filter tabs narrow the list (all, invite pending, stale, gaps, top recognizers). "Last recognition from manager" is the date a person last received recognition from their manager, with a ⚠ when it is old. All of it follows the date range chosen on the page (D8). The POC (the proof-of-concept branch zach/11074/manager-drilldown) has code to port.

Outcome: The page shows the signals and filter tabs, driven by the page date range.

Acceptance criteria:

Last recognition from manager is shown, with ⚠ and a tooltip.
Signal chips are shown, with hover definitions.
Newly displayed IDs are coalesced into bounded metadata requests with at most one or two in flight; no request is sent per row.
Pending/error states are visible, metadata can be retried, and identity rows remain usable after a failure.
Initial loading does not request every tab count. Selected filters return exact full-subtree results; known unsearched badges may be displayed.
A period/context change invalidates obsolete metadata and count responses. Returned manager IDs are checked against the displayed branch.
Collapsed/removed rows do not schedule further metadata; cancellation does not assume that server queries have stopped.
"Reports to …" appears in filtered views.
Tests: feature specs.

Implementation notes:

Hydrate stable person IDs rather than row positions. Use request-context guards and the server's exact resolved range.

Sketch:

Each row's calculated cells move from loading to ready, or to a failure that can be retried. Hovering the ⚠ explains it.

Proposed code (a sketch of the shape, not final):

const queue = new Set()
let inFlight = 0
let context = currentContext()                           // period, filter, sort, page

export function hydrate(ids) {
  ids.forEach((id) => queue.add(id))
  pump()
}

const pump = debounce(async () => {
  while (inFlight < 2 && queue.size) {                   // at most two requests at once
    const batch = take(queue, 50)                        // the server enforces its own cap too
    const sent = context
    inFlight++
    try {
      const res = await fetchJson(`/manager/team/metadata?user_ids=${batch.join(",")}`)
      if (sent !== context) continue                     // late response: ignore it
      for (const [id, meta] of Object.entries(res.metadata)) {
        if (displayedParentId(id) !== meta.manager_id) refreshBranch(id)   // they moved
        else renderMetadata(id, meta)
      }
    } catch {
      markFailed(batch)                                  // visible retry, identity rows stay usable
    } finally {
      inFlight--
    }
  }
}, 50)

Waits on: G1, G2, U1, P5.

U3. Make the side panel work

Context: The side panel shows details about the person the manager clicks. P6 serves it as plain HTML. This ticket makes it look right and behave properly: loading without a page reload and a period dropdown. The POC (the proof-of-concept branch zach/11074/manager-drilldown) has code to port.

Outcome: Clicking a person shows their details in the side panel without a page reload.

Acceptance criteria:

Clicking a row loads that person into the panel without a page reload.
Breadcrumb links and names open that person.
The panel has the activity period dropdown (presets only).
Personal activity loads independently. Load team activity explicitly requests manager aggregates and paged member lists.
The initial viewer panel does not automatically request whole-team activity.
Panel errors/retries and period changes use their own context, independent of the table.
Tests: feature specs.

Implementation notes:

Take P6's plain panel and make it look and work right.
Start from: the POC's my_team_controller.js.

Sketch:

Clicking a person swaps the panel in place. Team activity loads only after its button is pressed.

Waits on: P6 (panel).

U4. Let users close and reopen the panel

Context: While the side panel is open, the table is narrower. Users need to be able to close the panel for a full-width table and reopen it again.

Outcome: Users can close and reopen the side panel.

Acceptance criteria:

Closing the panel gives a full-width table.
"Your activity" reopens the panel.
The first two closes show the product spec's dismissible reopening hint.
Tests: feature specs.

Implementation notes:

Closing/reopening the panel does not force a table-wide metadata or aggregate reload.

Sketch:

Closing the panel gives a full-width table, and Your activity brings it back. The first two closes show a dismissible hint.

Waits on: U3.

U5. Make it work on tablets and phones

Context: The "My Team" page is built for a wide screen, with the side panel next to the table. On tablets and phones there isn't room for that, so the layout adapts.

Outcome: "My Team" works on tablets and phones.

Acceptance criteria:

On tablets and phones, the panel becomes a drawer.
On phones the drawer is full screen, and signals sit next to names.
The filter bar stacks, and nothing scrolls sideways.
Tests: feature specs on tablet and phone.

Implementation notes:

The drawer behavior follows the product spec's approximately 1100px boundary (D4).

Sketch:

On a tablet the panel is a drawer over the table. On a phone it fills the screen, and signals sit under each name.

Waits on: U1–U4.

Decisions

Decided for now (we can revisit any of these).

D1. Tabs. Use Golditable's regular tab controls with optional count badges and period-specific labels. No automatic all-tab-count request.
D2. Panel lifecycle. Personal activity and explicit team activity are separate. Closing/reopening and the dismissible hint follow the product spec without reloading the whole tree.
D3. Expansion. Individual row expansion/collapse only; no Expand all, Collapse all, subtree endpoint, or mandatory restoration across page/sort changes.
D4. Responsive layout. Follow the product spec's drawer/full-screen behavior and approximately 1100px transition.
D5. Data boundaries. Service results are typed data. Golditable adapters may render cells, but loading/failed metadata is never represented as zero, false, or "none yet".
D6. Freshness and access. New requests read live data. Browser reuse is scoped to the view; it does not grant access after a person moves or becomes ineligible. There is no server-side five-minute report cache.
D7. Recognition policy. Count only delivered peer-to-peer recognition: recognition sent by a person (not the system) with successful recipients. Anniversary recognition and nomination awards never count. Private recognition counts in the metrics. Cross-company recognition is ignored, because the product does not permit it.
D8. Periods. Accept only 30d, 90d and 12m, where 12m means 365 days. Every range ends now and includes today up to the moment of the request, resolved centrally to company-local days and UTC bounds. The thresholds 4, 13 and 52 are stored explicitly. The latest login is last_login_at. Historical custom ranges would need login, state and assignment history, so they are not a date-picker-only change.
D9. Calculation. Standard live Rails queries, grouped by fact grain, are the initial backend. Asynchronous metadata is a bounded HTTP request, not a job. C5 measures the architecture's stated targets before rollout; caching or materialization requires separate evidence and scope/freshness design.
D10. Disabled intermediary. A disabled manager is treated as if the people below them have no manager, so those people do not appear on the manager page. The page covers managers and their direct reports. Counts, tree traversal and access checks all follow this same rule.
D11. Nested paging. The page size is 25 by default and comes from the team_page_size InternalSetting, so it can be changed without a deploy. It applies to the first page of the table and to every page of an opened group. The server never allows more than 50, whatever the setting says, and a missing or invalid setting falls back to 25. If they have more, a "Show N more" row at the end of the group loads the next page. The next page is found by a cursor (the sort value and ID of the last row seen), not by an offset, so people who move or are added between clicks never cause repeats or gaps. There is no numbered pager inside a group, because Golditable's pager only pages the top-level rows. "Show more" stops once the page has a set number of rows rendered (set from C5's measurements) and points to search instead. Top-level rows keep Golditable's normal pager.