Performance And Localization Roadmap (2 to 100 Languages)

This roadmap translates the current architecture review into an implementation sequence for:

• workers/my-api API performance at larger data volumes
• apps/dashboard localization architecture for 100 languages
• multi-language search and fallback behavior across UI and API

Implementation backlog: Performance And Localization Implementation Backlog

Goals

Primary goals:

• keep p95 dashboard API list endpoints under 400ms at target data volume
• support 100 UI and content locales without major bundle-size regressions
• provide locale-aware search and deterministic fallback behavior
• preserve current product behavior while migrating in safe increments

Non-goals in this plan:

• redesigning ingestion enrichment providers
• changing core sharding strategy (unless explicitly called out in later phase options)

Current Constraints (Baseline)

Observed constraints to address:

• cross-shard list endpoints over-fetch with page * perPage per shard and then sort in memory
• search queries use English-only JSON paths (for example $.en)
• dashboard i18n statically imports locale resources into the initial bundle
• localized UI field components are hardcoded for only en and pt
• some date labels are formatted server-side in en-US

Delivery Model

• Phase duration: 1 to 3 weeks each
• Gate: each phase has explicit acceptance criteria and rollback strategy
• Deployment rule for worker changes: validate by production deploy + production route checks

Phase 0: Baseline, Guardrails, And Instrumentation (Week 1)

Objective: establish measurable baseline before behavioral changes.

Work items

1. Add structured timing and cardinality logs to dashboard-api list handlers.
2. Emit per-request metrics:

• shard query count
• rows fetched before merge
• rows returned after pagination
• end-to-end duration

3. Add dashboard web-vitals and i18n timing marks:

• app boot time
• i18n init time
• locale switch latency

4. Define load-test fixtures for:

• publications list with deep page values
• people list with search and filters
• locale switching across many namespaces

Acceptance criteria

• baseline p50/p95 metrics recorded for 7 days in production
• top 3 slow query patterns identified with sample requests
• no user-facing behavior changes

Phase 1: Quick Wins (Low Risk) (Week 2)

Objective: reduce immediate cost without schema redesign.

dashboard-api

1. Cache frequently requested list pages for short TTLs with cache keys that include:

• workspace/entity
• all query filters
• page/perPage/sort/dir

2. Add selective invalidation on write operations for affected namespaces.
3. Move server-generated chart labels to client-side formatting by returning canonical keys only.

dashboard

1. Set explicit TanStack Query defaults in root QueryClient for high-read endpoints:

• staleTime for list/read-heavy data
• bounded retry policy for 5xx and 429 only
• refetch behavior tuned per route

2. Add optimistic locale switch prefetch for active route namespace.

Acceptance criteria

• p95 for cached list requests improves by at least 30%
• zero correctness regressions in list totals and pagination metadata
• timeseries labels render correctly in active locale

Phase 2: Scalable Pagination And Query Path (Week 3 to 5)

Objective: remove page-depth amplification from cross-shard fan-out.

Option A (recommended first): Cursor pagination with k-way merge

1. Introduce cursor-based list contracts for publications and people endpoints.
2. Query each shard with per-shard cursor and fixed shard page window.
3. Merge sorted shard streams using k-way merge, emit next cursor.
4. Keep legacy page/perPage endpoints temporarily behind compatibility adapter.

Option B (later if needed): Aggregation index table

1. Build a denormalized listing index per workspace keyed by sortable fields.
2. Read list endpoints primarily from index table.
3. Keep source-of-truth writes in primary tables.

Acceptance criteria

• endpoint complexity no longer grows with requested page depth
• deep navigation (equivalent of page 50+) remains within SLO
• response ordering is stable and deterministic

Rollback strategy

• keep legacy pagination path behind feature flag
• per-route switch to old path if cursor path degrades

Phase 3: 100-Language Frontend i18n Architecture (Week 4 to 6)

Objective: remove static-locale assumptions and keep bundle growth controlled.

dashboard i18n runtime

1. Replace static locale imports with lazy loading by locale + namespace.
2. Preload only fallback locale on boot.
3. Add route-level namespace loading for heavy sections.
4. Introduce locale registry (from config/API), not hardcoded array.

UI and forms

1. Refactor localized inputs from fixed tabs (en/pt) to dynamic language selector.
2. Add search/filter in language selector for large locale sets.
3. Add clear fallback indicator when value shown is from fallback locale.

Routing and locale handling

1. Expand locale normalization to support full BCP-47 tags where needed.
2. Keep canonical URL policy (default locale path elision) with explicit redirects.

Acceptance criteria

• initial JS bundle increase from adding 98 locales stays under 10%
• locale switch to uncached locale renders in under 500ms p95
• no hardcoded en/pt assumptions in runtime code paths

Phase 4: Multi-Language Data And Search (Week 6 to 9)

Objective: make content search and fallback truly locale-aware.

Data model and indexing

1. Introduce searchable projection layer for localized fields:

• localized search table per entity-language OR
• FTS table with language-tagged entries

2. Populate projection asynchronously from writes/ingestion updates.
3. Add migration scripts and backfill jobs for existing records.

API changes

1. Add locale and fallback parameters to list/search endpoints.
2. Rank matches by requested locale first, then fallback chain.
3. Return metadata:

• matched_locale
• fallback_used boolean

Acceptance criteria

• searching in non-English locale returns expected records
• search latency remains within SLO under full dataset
• fallback semantics are deterministic and documented

Phase 5: Translation Operations, QA, And Rollout (Week 8 to 10)

Objective: operationalize 100-language support safely.

Operations

1. Define translation source of truth and sync pipeline.
2. Add missing-key detection in CI for all namespaces.
3. Add pseudo-locale in QA for overflow/truncation checks.
4. Add translation freeze + release checklist.

QA matrix

1. Tier-1 locales: full regression on each release.
2. Tier-2 locales: sampled smoke coverage.
3. RTL validation plan (if/when RTL locales are enabled).

Rollout strategy

1. Feature-flag locale cohorts (10 -> 25 -> 50 -> 100).
2. Monitor error rates, missing key rates, and performance per cohort.
3. Auto-disable newly enabled locales if error threshold exceeded.

Acceptance criteria

• 100 locales enabled in production behind controlled rollout
• no severe UX regressions from text overflow in tier-1 locales
• dashboard-api and dashboard SLOs still met after full rollout

API Contract Changes Summary

Planned changes to coordinate early with consumers:

1. List endpoints add cursor-based variants.
2. Search endpoints accept locale context.
3. Responses include locale metadata fields for transparency.
4. Timeseries endpoints return canonical period keys only.

Testing Plan By Phase

1. Unit tests

• locale fallback resolution
• cursor encoding/decoding and sort stability
• search ranking precedence by locale

2. Integration tests

• cross-shard cursor traversal
• locale-aware search end-to-end
• cache invalidation on write paths

3. Production verification

• deploy workers for worker-side changes
• verify production routes and observability dashboards

Suggested Owners

1. API performance stream: dashboard-api maintainers
2. Frontend i18n stream: dashboard maintainers
3. Search/index stream: shared API + data owners
4. Translation ops stream: docs/product ops + frontend

Milestone Checklist

1. M0 Baseline metrics complete
2. M1 Quick wins shipped
3. M2 Cursor pagination live for publications and people
4. M3 Lazy-loaded i18n live with dynamic locale registry
5. M4 Locale-aware search live
6. M5 100-language rollout complete

Risks And Mitigations

1. Risk: cursor migration breaks clients

• Mitigation: dual-run old and new list contracts until parity sign-off

2. Risk: i18n lazy loading introduces flash/missing text

• Mitigation: suspense fallback + namespace prefetch on route transition

3. Risk: search index lag after writes

• Mitigation: write-through updates for critical fields + lag monitoring

4. Risk: translation quality variance across 100 locales

• Mitigation: tiered QA and staged rollout by locale cohort

Immediate Next Actions (This Week)

1. Approve Phase 0 instrumentation scope and SLO targets.
2. Create implementation tickets for Phase 1 and Phase 2 design spike.
3. Decide between projection-table vs FTS approach for Phase 4.
4. Define locale registry source (config file vs API-managed).

Last updated: March 28, 2026