perf(api): batch project-list user and avatar expansions

[GODOSTROYER]

Description

The public project-list endpoint performs repeated user and avatar reads when a page expands user relationships. For example, fields=id,name,created_by,updated_by&expand=created_by,updated_by on 100 projects with uploaded-avatar audit users issued 408 SQL statements in the local request-stack benchmark.

This follow-up to #9717 batches included created_by, updated_by, project_lead, and default_assignee expansions together with their avatar assets. It intersects expand with fields, allowlists the supported relationships, and retains the existing project-lead join. Other users use their base manager to preserve ordinary foreign-key lookup semantics, including inactive historical users.

The change is confined to the list GET handler and regression tests. Serialization, permissions, ordering, pagination, writes, and schema remain unchanged. Cover-image loading is outside this scope.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• Feature (non-breaking change which adds functionality)
• Improvement (change that would cause existing functionality to not work as expected)
• Code refactoring
• Performance improvements
• Documentation update

Screenshots and Media (if applicable)

Not applicable.

Test Scenarios

• 732 backend tests passed in the repository's Linux Docker Compose stack and Windows test environment, including 32 new regression cases. The final regression file against the pristine base produced 21 failures and 11 passes, demonstrating the missing loading guarantees.
• Coverage includes all four expansions, sparse fields, exact user/avatar identity, shared users across roles, null/inactive users, soft-deleted avatars, bounded HTTP query growth, query-free serialization after page loading, visibility, empty results, and cursor pagination.
• Changed-file Ruff lint/formatting, copyright, Django system checks, and migration-drift checks passed. The 92 full-suite warnings are existing factory_boy/openpyxl deprecations; none originate in the changed files.
• Local validation is separate from hosted GitHub checks and maintainer review.

6 October 2026 rerun of the corrected published harness: local 100-project audit-user measurements (20 randomized trials per variant after two warmups; SQL counts captured separately from timing):

Fixture	SQL statements, before → after	Median, before → after	IQR, before → after
Distinct uploaded-avatar users	408 → 10	1245.3 → 464.4 ms	325.0 → 172.5 ms
Shared uploaded-avatar users	408 → 10	1538.7 → 396.9 ms	654.3 → 250.6 ms
Null audit-user relations	8 → 8	112.0 → 124.2 ms	45.4 → 62.8 ms

Responses were identical. These measurements cover APIClient.get plus JSON parsing for fields=id,name,created_by,updated_by&expand=created_by,updated_by, rather than TCP or production traffic. The A/B harness reconstructs legacy loading by removing only the new expansion prefetches at pagination; the pristine-base regression run is separate. The null-user median increased by about 12 ms, and the distinct-user optimized IQR is broad; no statistical-significance or universal latency claim is made. Real replica routing and production-scale workspaces were not exercised. Earlier 5 October measurements are preserved unchanged in the historical evidence archive; the table above uses the latest replay.

References

• Follow-up to the project-list N+1 work explicitly deferred in fix(api): expand=updated_by returns the user, and null relations stay null #9717.
• Reproduction commands, strategy decision, raw trials, SQL accounting, and validation logs. The evidence packet is hosted separately on my fork; this PR contains only the application change and regression tests.

Summary by CodeRabbit

• Performance
  • Improved project list loading for expanded user details, reducing additional database queries as result pages grow.
  • Preserved existing project visibility, response formats, and pagination behavior.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 759ed3b1-575a-4eeb-b123-00ea77952071

📥 Commits

Reviewing files that changed from the base of the PR and between 7466675 and a96adb7.

📒 Files selected for processing (2)

• apps/api/plane/api/views/project.py
• apps/api/plane/tests/contract/api/test_project_list_expansion_queries.py

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The project list now batches avatar-asset loading for expanded user fields, while respecting requested sparse fields. Contract tests cover serialized user data, query counts, visibility, and pagination behavior.

Changes

Project list user expansions

Layer / File(s)	Summary
Expansion loading and serialization apps/api/plane/api/views/project.py, apps/api/plane/tests/contract/api/test_project_list_expansion_queries.py	The endpoint prefetches avatar assets for expanded user fields and uses local fields and expand values during serialization. Tests check query-free serialization, sparse fields, and user representations.
HTTP response and pagination contracts apps/api/plane/tests/contract/api/test_project_list_expansion_queries.py	HTTP tests check query counts, project visibility, null references, empty results, and cursor pagination against baseline responses.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Refactor

Merge Risk: ⚪ Minimal · up to a96ad

The project-list expansion change is ready to merge after normal checks; no concrete response or loading regression remains identified.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 87.50% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 2 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely identifies the main change: batching project-list user and avatar expansions for performance.
Description check	✅ Passed	The description covers the change, type, screenshots, test scenarios, and references. It provides concrete implementation details and validation results; screenshots are marked not applicable.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}