Performance And Localization Implementation Backlog

This backlog is designed for direct execution by a coding agent.

Scope:

• apps/dashboard
• workers/my-api
• packages/schemas
• migrations
• tests

Linked roadmap: Performance And Localization Roadmap (2 to 100 Languages)

How To Use This Backlog

Execution rules:

1. Implement tickets in priority order unless dependencies state otherwise.
2. Keep pull requests scoped to one ticket only.
3. For worker changes, deploy and verify production routes before closing ticket.
4. Do not start Phase N+1 tickets before all blocking tickets in Phase N are complete.

Ticket status model:

• Todo
• In Progress
• Blocked
• Done

Epic A: Baseline And Observability (Phase 0)

A1. Add list-endpoint performance metrics

• Priority: P0
• Status: Todo
• Owners: dashboard-api maintainers
• Dependencies: none
• Target files:
  • workers/my-api/src/features/publications/handlers.ts
  • workers/my-api/src/features/people/handlers.ts
• Tasks:
  • add timing logs for request start/end
  • log shard count, rows fetched pre-merge, rows returned post-pagination
  • include query shape metadata (sort, dir, page/perPage, filters present)
• Acceptance criteria:
  • logs emitted for list endpoints on every request
  • no response schema changes
  • no measurable increase in error rate
• Verification:
  • deploy worker
  • confirm logs in production for 24h

Agent prompt for A1

Implement ticket A1 from the Performance And Localization Implementation Backlog.

Objective:
Add structured performance and cardinality metrics to dashboard-api list handlers with no response contract changes.

Scope:

- workers/my-api/src/features/publications/handlers.ts
- workers/my-api/src/features/people/handlers.ts

Requirements:

1. Add request-level timing for list endpoints:

- total handler duration in milliseconds
- timing starts before query parsing and ends before response return

2. Add shard and cardinality metrics:

- shard_count
- rows_fetched_pre_merge
- rows_returned_post_pagination
- query_shape metadata containing:
  - sort
  - dir
  - page
  - perPage or per_page (as applicable)
  - boolean flags for filters present (q, status, visibility, publication_type, publication_year, min_cited_by, category_id, affiliation_status, active_only)

3. Keep behavior unchanged:

- do not modify API response body shape
- do not modify status codes
- do not change business logic, filtering, sorting, or pagination behavior

4. Logging constraints:

- use structured log objects, not free-form strings
- include route identifier and workspace/entity id when available
- avoid logging sensitive payload content

5. Tests and validation:

- add or update tests that verify instrumentation does not alter response contracts
- run relevant tests for modified handlers

6. Production verification (required for worker changes):

- deploy dashboard-api
- verify production list routes still behave correctly
- confirm instrumentation logs are emitted for at least one publications list request and one people list request

Deliverables:

- code changes
- tests
- concise verification report with:
  - endpoints exercised
  - sample structured metric log fields observed
  - confirmation that response contracts remained unchanged

Constraints:

- keep changes minimal and localized to ticket A1
- do not implement caching or cursor pagination in this ticket

A2. Add dashboard-side performance marks for i18n lifecycle

• Priority: P1
• Status: Todo
• Owners: dashboard maintainers
• Dependencies: none
• Target files:
  • apps/dashboard/src/main.tsx
  • apps/dashboard/src/lib/i18n.ts
  • apps/dashboard/src/routes/{-$locale}.tsx
• Tasks:
  • add timing marks for boot, i18n init complete, locale switch complete
  • expose diagnostics in debug mode only
• Acceptance criteria:
  • timings visible in debug output
  • no user-visible UI changes

A3. Build repeatable load-test scripts for list endpoints

• Priority: P1
• Status: Todo
• Owners: shared API/testing
• Dependencies: A1
• Target files:
  • tests/features/build/ (new scripts)
  • tests/runners/index.mjs (or equivalent wiring)
• Tasks:
  • add scenarios for deep pagination on publications and people
  • output p50/p95 and row cardinality stats
• Acceptance criteria:
  • script runs against production host with read-only calls
  • baseline report generated and committed under docs artifacts

Epic B: Quick Wins (Phase 1)

B1. Add KV caching for expensive list query shapes

• Priority: P0
• Status: Todo
• Owners: dashboard-api maintainers
• Dependencies: A1
• Target files:
  • workers/my-api/src/features/publications/handlers.ts
  • workers/my-api/src/features/people/handlers.ts
• Tasks:
  • add short TTL cache for repeated list query shapes
  • include workspace/entity and all filters in cache key
  • bypass cache for highly volatile shapes if needed
• Acceptance criteria:
  • cache hit ratio >= 40 percent on common list routes
  • p95 latency improves >= 30 percent on cached routes

B2. Add selective cache invalidation on mutation paths

• Priority: P0
• Status: Todo
• Owners: dashboard-api maintainers
• Dependencies: B1
• Target files:
  • workers/my-api/src/features/publications/handlers.ts
  • workers/my-api/src/features/people/handlers.ts
• Tasks:
  • invalidate relevant list cache namespaces on writes
  • keep invalidation targeted by workspace when possible
• Acceptance criteria:
  • no stale list data after write beyond configured TTL
  • invalidation operations complete without error spikes

B3. Return canonical period keys only from timeseries endpoints

• Priority: P1
• Status: Todo
• Owners: dashboard-api maintainers
• Dependencies: none
• Target files:
  • workers/my-api/src/features/publications/helpers.ts
  • workers/my-api/src/features/publications/handlers.ts
• Tasks:
  • remove en-US label generation from API
  • return stable period keys and counts only
• Acceptance criteria:
  • API contract updated and documented
  • dashboard formats labels client-side per active locale

B4. Set root query defaults for list-heavy dashboard routes

• Priority: P1
• Status: Todo
• Owners: dashboard maintainers
• Dependencies: none
• Target files:
  • apps/dashboard/src/routes/__root.tsx
  • apps/dashboard/src/features/publications/queries.ts
  • apps/dashboard/src/features/people/queries.ts
• Tasks:
  • set default staleTime/retry/refetch policies for high-read endpoints
  • avoid refetch storms on focus/reconnect for stable pages
• Acceptance criteria:
  • request volume reduced in normal dashboard usage
  • no regression in perceived freshness for critical views

Epic C: Cursor Pagination And Merge Scalability (Phase 2)

C1. Add cursor-based schema contracts for list endpoints

• Priority: P0
• Status: Todo
• Owners: dashboard-api + schemas
• Dependencies: A1
• Target files:
  • packages/schemas/src/index.ts
  • workers/my-api/src/features/publications/routes.ts
  • workers/my-api/src/features/people/routes.ts
• Tasks:
  • define cursor query and response schemas
  • keep existing page/perPage contracts active for compatibility
• Acceptance criteria:
  • new cursor endpoints validated by Zod
  • old endpoints unchanged and still functional

C2. Implement per-shard cursor windows + k-way merge for publications

• Priority: P0
• Status: Todo
• Owners: dashboard-api maintainers
• Dependencies: C1
• Target files:
  • workers/my-api/src/features/publications/handlers.ts
• Tasks:
  • fetch fixed windows per shard using cursor state
  • merge by requested sort/dir in deterministic order
  • emit next cursor token
• Acceptance criteria:
  • deep traversal latency does not scale linearly with page depth
  • stable ordering validated by integration tests

C3. Implement per-shard cursor windows + k-way merge for people

• Priority: P0
• Status: Todo
• Owners: dashboard-api maintainers
• Dependencies: C1
• Target files:
  • workers/my-api/src/features/people/handlers.ts
• Tasks:
  • same strategy as C2 for people listing
• Acceptance criteria:
  • deep traversal remains within SLO
  • deterministic ordering and no duplicate records

C4. Add dashboard adapters for cursor navigation

• Priority: P1
• Status: Todo
• Owners: dashboard maintainers
• Dependencies: C2, C3
• Target files:
  • apps/dashboard/src/features/publications/queries.ts
  • apps/dashboard/src/features/people/queries.ts
  • relevant route components
• Tasks:
  • implement cursor navigation UI while preserving current UX
  • maintain compatibility with existing page URLs where required
• Acceptance criteria:
  • users can navigate forward/backward reliably
  • no blocking UI regressions

Epic D: Frontend i18n Runtime For 100 Locales (Phase 3)

D1. Replace static i18n imports with lazy locale+namespace loading

• Priority: P0
• Status: Todo
• Owners: dashboard maintainers
• Dependencies: none
• Target files:
  • apps/dashboard/src/lib/i18n.ts
  • apps/dashboard/src/locales/ (loader strategy)
• Tasks:
  • load fallback locale at boot only
  • dynamically load active locale namespaces on demand
• Acceptance criteria:
  • adding 98 locales does not materially increase initial bundle
  • uncached locale switch remains under 500ms p95

D2. Introduce locale registry (dynamic, not hardcoded)

• Priority: P0
• Status: Todo
• Owners: dashboard + dashboard-api
• Dependencies: D1
• Target files:
  • apps/dashboard/src/lib/locale.ts
  • apps/dashboard/src/components/layout/LanguageSwitcher.tsx
  • optional API endpoint for locale config
• Tasks:
  • support runtime locale list source
  • keep default locale behavior consistent
• Acceptance criteria:
  • no code changes required to add a locale
  • switcher renders dynamic locale set correctly

D3. Refactor localized input UX from fixed en/pt tabs to dynamic language selector

• Priority: P1
• Status: Todo
• Owners: dashboard maintainers
• Dependencies: D2
• Target files:
  • apps/dashboard/src/components/forms/LocalizedField.tsx
  • forms using localized fields
• Tasks:
  • support editing multiple locales with scalable selector UX
  • include fallback indicator and missing translation cues
• Acceptance criteria:
  • component supports 100 locales without rendering 100 tabs
  • keyboard and accessibility behavior preserved

D4. Extend locale handling to full BCP-47 where needed

• Priority: P2
• Status: Todo
• Owners: dashboard maintainers
• Dependencies: D2
• Target files:
  • apps/dashboard/src/lib/locale.ts
  • locale route normalization logic
• Tasks:
  • support language-region tags and stable normalization
• Acceptance criteria:
  • locale parsing behavior documented and tested

Epic E: Multi-Language Search And Fallback (Phase 4)

E1. Decision spike: projection-table vs FTS strategy

• Priority: P0
• Status: Todo
• Owners: API + data owners
• Dependencies: A3
• Deliverable:
  • ADR documenting chosen strategy, trade-offs, and migration plan
• Acceptance criteria:
  • strategy approved with performance estimates and operational cost

E2. Implement localized search projection and backfill

• Priority: P0
• Status: Todo
• Owners: dashboard-api + migrations
• Dependencies: E1
• Target files:
  • migrations/ (new migration)
  • workers/my-api search handlers
  • background/backfill scripts
• Tasks:
  • create projection/index structures
  • backfill existing data with resumable process
• Acceptance criteria:
  • projection coverage reaches 100 percent of existing records
  • backfill can be resumed safely after interruption

E3. Add locale-aware query parameters and response metadata

• Priority: P0
• Status: Todo
• Owners: dashboard-api + schemas
• Dependencies: E2
• Target files:
  • packages/schemas/src/index.ts
  • workers/my-api list/search handlers
  • docs reference pages
• Tasks:
  • add locale and fallback parameters
  • return matched_locale and fallback_used metadata
• Acceptance criteria:
  • non-English searches produce expected results
  • fallback behavior deterministic and documented

E4. Add ranking tests for locale precedence

• Priority: P1
• Status: Todo
• Owners: testing + API maintainers
• Dependencies: E3
• Target files:
  • tests/features/
• Tasks:
  • verify ranking order requested-locale first, then fallback chain
• Acceptance criteria:
  • test suite catches ranking regressions

Epic F: Translation Operations And Rollout (Phase 5)

F1. Add missing-key CI checks per namespace and locale

• Priority: P1
• Status: Todo
• Owners: dashboard + docs ops
• Dependencies: D1
• Target files:
  • CI workflow config
  • scripts for locale validation
• Acceptance criteria:
  • build fails on missing required keys for tier-1 locales

F2. Add pseudo-locale for expansion and truncation QA

• Priority: P2
• Status: Todo
• Owners: dashboard maintainers
• Dependencies: D1
• Acceptance criteria:
  • pseudo-locale available in non-production builds
  • overflow defects become visible in QA

F3. Execute staged locale cohort rollout (10 -> 25 -> 50 -> 100)

• Priority: P0
• Status: Todo
• Owners: product + engineering
• Dependencies: D3, E3, F1
• Tasks:
  • roll out by cohorts behind feature flags
  • monitor error rates and performance per cohort
  • auto-disable problematic cohorts based on thresholds
• Acceptance criteria:
  • 100 locales enabled with SLO adherence

Agent Prompts By Ticket

A1 prompt

Use the detailed prompt in A1. Add list-endpoint performance metrics.

A2 prompt

Implement ticket A2 from performance-i18n-implementation-backlog.

Scope:

- apps/dashboard/src/main.tsx
- apps/dashboard/src/lib/i18n.ts
- apps/dashboard/src/routes/{-$locale}.tsx

Requirements:

- Add performance marks for app boot, i18n init complete, and locale switch complete.
- Expose diagnostics only when debug mode is enabled.
- Keep user-visible behavior unchanged.
- Add tests if existing debug/perf utilities are covered.

Deliverables:

- code changes
- tests (if applicable)
- short note with sample timing output

A3 prompt

Implement ticket A3 from performance-i18n-implementation-backlog.

Scope:

- tests/features/build/ (new scripts)
- tests/runners/index.mjs (or equivalent test runner wiring)

Requirements:

- Add repeatable read-only load scenarios for publications and people list endpoints.
- Include deep pagination and filtered search variants.
- Output p50/p95 latency and rows/cardinality metrics.
- Document how to run the scenarios against production safely.

Deliverables:

- test scripts
- runner integration
- generated sample baseline report format

B1 prompt

Implement ticket B1 from performance-i18n-implementation-backlog.

Scope:

- workers/my-api/src/features/publications/handlers.ts
- workers/my-api/src/features/people/handlers.ts

Requirements:

- Add short TTL KV caching for expensive list query shapes.
- Cache keys must include workspace/entity and full query shape.
- Keep API response contracts unchanged.
- Add tests for cache hit/miss behavior and correctness.

Mandatory verification:

- Deploy dashboard-api.
- Verify production list routes and observe cache hit behavior.

Deliverables:

- code changes
- tests
- production verification notes

B2 prompt

Implement ticket B2 from performance-i18n-implementation-backlog.

Scope:

- workers/my-api/src/features/publications/handlers.ts
- workers/my-api/src/features/people/handlers.ts

Requirements:

- Add selective cache invalidation on relevant mutation paths.
- Target invalidation by workspace namespace whenever possible.
- Avoid broad cache wipes unless strictly necessary.
- Add tests ensuring stale list data is not served after writes.

Mandatory verification:

- Deploy dashboard-api.
- Verify production write -> read flow reflects updates.

Deliverables:

- code changes
- tests
- invalidation strategy summary

B3 prompt

Implement ticket B3 from performance-i18n-implementation-backlog.

Scope:

- workers/my-api/src/features/publications/helpers.ts
- workers/my-api/src/features/publications/handlers.ts
- apps/dashboard consumer for timeseries labels

Requirements:

- Remove server-side en-US label formatting from timeseries responses.
- Return canonical period keys and counts.
- Update dashboard to render localized labels client-side.
- Keep chart behavior and data correctness unchanged.

Mandatory verification:

- Deploy dashboard-api.
- Verify production timeseries endpoint and dashboard rendering.

Deliverables:

- code changes across API + dashboard
- tests
- API contract update note

B4 prompt

Implement ticket B4 from performance-i18n-implementation-backlog.

Scope:

- apps/dashboard/src/routes/\_\_root.tsx
- apps/dashboard/src/features/publications/queries.ts
- apps/dashboard/src/features/people/queries.ts

Requirements:

- Set explicit root query defaults for list-heavy routes.
- Tune staleTime/retry/refetch policies to reduce unnecessary requests.
- Preserve data freshness for critical views.
- Add/adjust query tests where present.

Deliverables:

- code changes
- tests (if applicable)
- short before/after request-volume summary method

C1 prompt

Implement ticket C1 from performance-i18n-implementation-backlog.

Scope:

- packages/schemas/src/index.ts
- workers/my-api/src/features/publications/routes.ts
- workers/my-api/src/features/people/routes.ts

Requirements:

- Add cursor-based query/response schemas for list endpoints.
- Keep existing page/perPage contracts active and backward compatible.
- Wire route validation for new cursor contracts.
- Add schema and route tests.

Mandatory verification:

- Deploy dashboard-api.
- Verify both legacy and cursor route contracts in production.

Deliverables:

- schema + route changes
- tests
- compatibility notes

C2 prompt

Implement ticket C2 from performance-i18n-implementation-backlog.

Scope:

- workers/my-api/src/features/publications/handlers.ts

Requirements:

- Implement per-shard cursor windows with deterministic k-way merge.
- Emit next cursor token for forward traversal.
- Preserve sorting semantics and response correctness.
- Add integration tests for ordering and duplicate prevention.

Mandatory verification:

- Deploy dashboard-api.
- Validate production deep traversal performance and ordering.

Deliverables:

- handler implementation
- tests
- measured deep-page behavior summary

C3 prompt

Implement ticket C3 from performance-i18n-implementation-backlog.

Scope:

- workers/my-api/src/features/people/handlers.ts

Requirements:

- Implement per-shard cursor windows with deterministic k-way merge for people list.
- Emit next cursor token and maintain stable sort behavior.
- Prevent duplicates across shard merges.
- Add integration tests for ordering, dedupe, and pagination continuity.

Mandatory verification:

- Deploy dashboard-api.
- Validate production deep traversal performance and correctness.

Deliverables:

- handler implementation
- tests
- verification report

C4 prompt

Implement ticket C4 from performance-i18n-implementation-backlog.

Scope:

- apps/dashboard/src/features/publications/queries.ts
- apps/dashboard/src/features/people/queries.ts
- related route components

Requirements:

- Add dashboard adapters for cursor navigation.
- Preserve current UX and URL compatibility requirements.
- Support forward and backward navigation cleanly.
- Add UI/integration tests for navigation continuity.

Deliverables:

- code changes
- tests
- migration notes for any legacy page bridge

D1 prompt

Implement ticket D1 from performance-i18n-implementation-backlog.

Scope:

- apps/dashboard/src/lib/i18n.ts
- apps/dashboard/src/locales/ loading strategy

Requirements:

- Replace static locale imports with lazy locale+namespace loading.
- Preload only fallback locale at boot.
- Load active locale namespaces on demand.
- Keep existing translations working during migration.
- Add tests for loading behavior and fallback safety.

Deliverables:

- i18n runtime changes
- tests
- bundle impact summary method (before/after)

D2 prompt

Implement ticket D2 from performance-i18n-implementation-backlog.

Scope:

- apps/dashboard/src/lib/locale.ts
- apps/dashboard/src/components/layout/LanguageSwitcher.tsx
- optional dashboard-api locale config endpoint

Requirements:

- Introduce runtime locale registry (not hardcoded language list).
- Keep default locale behavior and route canonicalization stable.
- Update switcher to render registry-driven locales.
- Add tests for locale normalization and registry handling.

Mandatory verification:

- If API endpoint is added/changed, deploy dashboard-api and verify production route.

Deliverables:

- code changes
- tests
- registry source documentation

D3 prompt

Implement ticket D3 from performance-i18n-implementation-backlog.

Scope:

- apps/dashboard/src/components/forms/LocalizedField.tsx
- forms consuming localized fields

Requirements:

- Replace fixed en/pt tabs with dynamic language selector UX.
- Support many locales without rendering one tab per locale.
- Add missing/fallback indicators and keep accessibility intact.
- Add component tests for large locale sets and keyboard behavior.

Deliverables:

- component refactor
- tests
- UX notes for editing and fallback flows

D4 prompt

Implement ticket D4 from performance-i18n-implementation-backlog.

Scope:

- apps/dashboard/src/lib/locale.ts
- locale route normalization logic

Requirements:

- Extend locale handling for BCP-47 tags where needed.
- Keep deterministic normalization and fallback rules.
- Preserve canonical URL behavior for default locale.
- Add tests for representative tags and edge cases.

Deliverables:

- locale parsing/normalization changes
- tests
- documented supported tag behavior

E1 prompt

Implement ticket E1 from performance-i18n-implementation-backlog.

Scope:

- architecture decision document (ADR) for localized search strategy

Requirements:

- Compare projection-table vs FTS options for D1/sharded architecture.
- Include performance expectations, migration plan, ops complexity, and risk.
- Recommend one approach with clear rationale.

Deliverables:

- ADR document committed in docs
- explicit recommendation and phased rollout plan

E2 prompt

Implement ticket E2 from performance-i18n-implementation-backlog.

Scope:

- migrations/ (new migration files)
- workers/my-api search handlers
- backfill scripts/jobs

Requirements:

- Implement localized search projection/index structures.
- Add resumable backfill process for existing records.
- Ensure projection updates on relevant writes.
- Add tests for projection correctness and backfill resume behavior.

Mandatory verification:

- Deploy dashboard-api (and run required migration process).
- Verify production read paths remain correct.

Deliverables:

- migrations
- API/backfill code
- tests
- operational runbook notes

E3 prompt

Implement ticket E3 from performance-i18n-implementation-backlog.

Scope:

- packages/schemas/src/index.ts
- workers/my-api list/search handlers
- docs reference pages

Requirements:

- Add locale-aware query parameters and fallback controls.
- Return matched_locale and fallback_used metadata in responses.
- Keep backward compatibility where feasible.
- Add tests for contract validation and response metadata behavior.

Mandatory verification:

- Deploy dashboard-api.
- Verify production routes with locale-aware queries.

Deliverables:

- schema + handler + docs updates
- tests
- compatibility note

E4 prompt

Implement ticket E4 from performance-i18n-implementation-backlog.

Scope:

- tests/features/

Requirements:

- Add ranking tests ensuring requested locale matches rank above fallback chain.
- Cover at least one multilingual fixture with competing locale hits.
- Ensure tests fail on ranking regressions.

Deliverables:

- integration tests
- fixtures
- brief explanation of ranking expectations

F1 prompt

Implement ticket F1 from performance-i18n-implementation-backlog.

Scope:

- CI workflow configuration
- locale validation scripts

Requirements:

- Add missing-key checks per namespace and locale.
- Enforce strict checks for tier-1 locales at minimum.
- Fail CI on missing required keys.
- Document how to run checks locally.

Deliverables:

- CI updates
- validation script(s)
- docs for local usage

F2 prompt

Implement ticket F2 from performance-i18n-implementation-backlog.

Scope:

- dashboard i18n config and locale assets for pseudo-locale

Requirements:

- Add pseudo-locale available in non-production builds.
- Ensure text expansion/character transformation exposes layout issues.
- Keep pseudo-locale hidden or disabled in production.
- Add tests for environment gating.

Deliverables:

- code/config changes
- tests
- QA usage note

F3 prompt

Implement ticket F3 from performance-i18n-implementation-backlog.

Scope:

- feature flag/config rollout controls
- monitoring hooks and threshold logic
- release/runbook docs

Requirements:

- Implement staged rollout cohorts: 10 -> 25 -> 50 -> 100 locales.
- Add per-cohort monitoring checks for error rate and performance.
- Add auto-disable mechanism when thresholds are exceeded.
- Document rollout and rollback operational steps.

Deliverables:

- rollout control implementation
- monitoring/guardrail integration
- runbook updates

Definition Of Done (Applies To Every Ticket)

1. Code changes merged with tests.
2. Docs updated when API contract or behavior changes.
3. Worker tickets verified on production routes post-deploy.
4. Observability signals show no critical regression after release.

Agent Handoff Template

Use this template to start a coding-agent run for one ticket:

Implement ticket <ID> from performance-i18n-implementation-backlog.

Constraints:

- Scope only ticket <ID>.
- Do not change unrelated behavior.
- Add/adjust tests required by acceptance criteria.
- For worker changes, deploy and verify production route behavior.

Deliverables:

- code changes
- tests
- doc updates
- short verification report with measured outcome

Suggested First Sprint (Recommended)

Sprint 1 candidate set:

1. A1 Add list-endpoint performance metrics
2. A2 Add dashboard i18n timing marks
3. B4 Set root query defaults
4. B3 Canonical period keys only

Rationale:

• low migration risk
• immediate performance and observability gains
• creates baseline needed for deeper changes in Phase 2 and 4

Last updated: March 29, 2026