mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-18 02:03:09 +00:00
71 lines
3.2 KiB
Markdown
71 lines
3.2 KiB
Markdown
# Repo Overview Should Read Cached State Only
|
|
|
|
Read `00-end-to-end-async-realtime-plan.md` first for the governing migration order, runtime constraints, and realtime client model this brief assumes.
|
|
|
|
## Problem
|
|
|
|
Repo overview currently forces PR sync and branch sync inline before returning data. That turns a read path into:
|
|
|
|
- repo fetch
|
|
- branch enumeration
|
|
- diff/conflict calculations
|
|
- GitHub PR listing
|
|
|
|
The frontend polls repo overview repeatedly, so this design multiplies slow work and ties normal browsing to sync latency.
|
|
|
|
## Current Code Context
|
|
|
|
- Organization overview entry point: `foundry/packages/backend/src/actors/organization/actions.ts`
|
|
- Repository overview implementation: `foundry/packages/backend/src/actors/repository/actions.ts`
|
|
- Branch sync poller: `foundry/packages/backend/src/actors/repository-branch-sync/index.ts`
|
|
- PR sync poller: `foundry/packages/backend/src/actors/repository-pr-sync/index.ts`
|
|
- Repo overview client polling: `foundry/packages/frontend/src/components/organization-dashboard.tsx`
|
|
|
|
## Target Contract
|
|
|
|
- `getRepoOverview` returns the latest cached repo projection immediately.
|
|
- Sync happens on a background cadence or on an explicit async refresh trigger.
|
|
- Overview responses include freshness metadata so the client can show "refreshing" or "stale" state without blocking.
|
|
|
|
## Proposed Fix
|
|
|
|
1. Remove inline `forceProjectSync()` from `getRepoOverview`.
|
|
2. Add freshness fields to the repository projection, for example:
|
|
- `branchSyncAt`
|
|
- `prSyncAt`
|
|
- `branchSyncStatus`
|
|
- `prSyncStatus`
|
|
3. Let the existing polling actors own cache refresh.
|
|
4. If the client needs a manual refresh, add a non-blocking command such as `repository.requestOverviewRefresh` that:
|
|
- enqueues refresh work
|
|
- updates sync status to `queued` or `running`
|
|
- returns immediately
|
|
5. Keep `getRepoOverview` as a pure read over repository SQLite state.
|
|
|
|
## Files Likely To Change
|
|
|
|
- `foundry/packages/backend/src/actors/organization/actions.ts`
|
|
- `foundry/packages/backend/src/actors/repository/actions.ts`
|
|
- `foundry/packages/backend/src/actors/repository/db/schema.ts`
|
|
- `foundry/packages/backend/src/actors/repository/db/migrations.ts`
|
|
- `foundry/packages/backend/src/actors/repository-branch-sync/index.ts`
|
|
- `foundry/packages/backend/src/actors/repository-pr-sync/index.ts`
|
|
- `foundry/packages/frontend/src/components/organization-dashboard.tsx`
|
|
|
|
## Client Impact
|
|
|
|
- The repo overview screen should render cached rows immediately.
|
|
- If the user requests a refresh, the UI should show a background sync indicator instead of waiting for the GET call to complete.
|
|
- Polling frequency can be reduced because reads are now cheap and sync is event-driven.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `getRepoOverview` does not call `force()` on polling actors.
|
|
- Opening the repo overview page does not trigger network/git work inline.
|
|
- Slow branch sync or PR sync no longer blocks the page request.
|
|
|
|
## Implementation Notes
|
|
|
|
- Favor adding explicit freshness metadata over implicit timing assumptions in the frontend.
|
|
- The overview query should remain safe to call frequently even if the UI still polls during the transition.
|
|
- Fresh-agent check: confirm no other read paths call `forceProjectSync()` inline after this change.
|