192 lines
9.3 KiB
Markdown
192 lines
9.3 KiB
Markdown
---
|
|
phase: 08-stack-upgrade-backend-decomposition
|
|
plan: 07
|
|
subsystem: api
|
|
tags: [frontend, api-client, barrel-reexport, decomposition, vue3, javascript]
|
|
|
|
# Dependency graph
|
|
requires:
|
|
- phase: 08-stack-upgrade-backend-decomposition/08-03
|
|
provides: useToastStore stub and session-revocation wiring (Wave 1 prerequisite)
|
|
provides:
|
|
- "frontend/src/api/utils.js: request() + fetchWithRetry() HTTP transport"
|
|
- "frontend/src/api/documents.js: document domain functions"
|
|
- "frontend/src/api/auth.js: auth domain functions"
|
|
- "frontend/src/api/topics.js: topics domain functions"
|
|
- "frontend/src/api/admin.js: admin domain functions with fetchWithRetry blob-download"
|
|
- "frontend/src/api/folders.js: folder domain functions"
|
|
- "frontend/src/api/shares.js: share domain functions"
|
|
- "frontend/src/api/cloud.js: cloud storage domain functions"
|
|
- "frontend/src/api/client.js: barrel re-export preserving 35+ consumer imports"
|
|
affects:
|
|
- "any plan adding new API functions — must add to appropriate domain module, not client.js"
|
|
- "08-08 and beyond — frontend API layer is now modular"
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added: []
|
|
patterns:
|
|
- "Barrel re-export: client.js is now ~20 lines of export* from domain modules"
|
|
- "fetchWithRetry: single authenticated non-JSON fetch helper for blob-download patterns"
|
|
- "Domain module decomposition: one file per API domain (documents/auth/admin/etc.)"
|
|
- "Circular import prevention: request() in utils.js, not client.js"
|
|
|
|
key-files:
|
|
created:
|
|
- frontend/src/api/utils.js
|
|
- frontend/src/api/documents.js
|
|
- frontend/src/api/auth.js
|
|
- frontend/src/api/topics.js
|
|
- frontend/src/api/admin.js
|
|
- frontend/src/api/folders.js
|
|
- frontend/src/api/shares.js
|
|
- frontend/src/api/cloud.js
|
|
modified:
|
|
- frontend/src/api/client.js
|
|
|
|
key-decisions:
|
|
- "request() moved to utils.js (not client.js) to break circular dep: domain modules import from utils.js; client.js re-exports from domain modules — both directions cannot exist in client.js"
|
|
- "fetchWithRetry() is the single authenticated non-JSON fetch helper — 3 blob-download functions now delegate to it instead of copy-pasting auth+retry boilerplate"
|
|
- "client.js barrel uses export * from domain modules so all 35+ consumer files need zero edits"
|
|
- "testAiConnection bug fixed: test expected GET with query params; implementation sent POST with JSON body — aligned to test expectation (GET is correct for a read-only connection test)"
|
|
|
|
patterns-established:
|
|
- "New API functions must go in the appropriate domain module (documents/auth/admin/folders/shares/cloud/topics.js), NOT in client.js"
|
|
- "client.js is permanently a barrel — never add logic to it"
|
|
- "Blob-download endpoints use fetchWithRetry() from utils.js — do not add new retry boilerplate"
|
|
|
|
requirements-completed: [CODE-04, CODE-08]
|
|
|
|
# Metrics
|
|
duration: 5min
|
|
completed: 2026-06-10
|
|
---
|
|
|
|
# Phase 8 Plan 07: Frontend API client decomposition Summary
|
|
|
|
**636-line client.js monolith decomposed into 7 domain modules + utils.js transport layer; client.js reduced to 20-line barrel re-export; 3 blob-download retry patterns consolidated into fetchWithRetry()**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** ~5 min
|
|
- **Started:** 2026-06-10T16:39:06Z
|
|
- **Completed:** 2026-06-10T16:44:03Z
|
|
- **Tasks:** 4
|
|
- **Files modified:** 9 (8 created, 1 rewritten)
|
|
|
|
## Accomplishments
|
|
- Created `utils.js` with `request()` (moved verbatim from client.js) and new `fetchWithRetry()` helper consolidating 3 blob-download patterns
|
|
- Created 7 domain modules (`documents.js`, `auth.js`, `topics.js`, `admin.js`, `folders.js`, `shares.js`, `cloud.js`) each importing from `utils.js`
|
|
- Rewrote `client.js` as a 20-line barrel re-export — all 36 consumer files continue importing from it without modification
|
|
- Fixed pre-existing bug: `testAiConnection` was sending POST+JSON but test expected GET+query-params; fixed to match the test contract
|
|
|
|
## Line Counts Before/After
|
|
|
|
| File | Before | After |
|
|
|------|--------|-------|
|
|
| `client.js` | 636 lines | 20 lines |
|
|
| `utils.js` | — | 119 lines (new) |
|
|
| `documents.js` | — | 87 lines (new) |
|
|
| `auth.js` | — | 97 lines (new) |
|
|
| `topics.js` | — | 39 lines (new) |
|
|
| `admin.js` | — | 166 lines (new) |
|
|
| `folders.js` | — | 46 lines (new) |
|
|
| `shares.js` | — | 36 lines (new) |
|
|
| `cloud.js` | — | 61 lines (new) |
|
|
|
|
**Total API layer:** 636 lines → 671 lines (spread across 9 focused files)
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task 1: Create utils.js with request() and fetchWithRetry()** - `80d6f37` (feat)
|
|
2. **Task 2: Create domain modules documents.js, auth.js, topics.js** - `fd9188b` (feat)
|
|
3. **Task 3: Create domain modules admin.js, folders.js, shares.js, cloud.js** - `a895b18` (feat)
|
|
4. **Task 4: Rewrite client.js as barrel re-export and run frontend tests** - `02bf04c` (feat)
|
|
|
|
## Consumer Files Confirmed Untouched (36 files)
|
|
|
|
All 36 consumer files import from `'../api/client.js'` or `'../../api/client.js'` and were zero-modified:
|
|
|
|
- **Stores (5):** `stores/auth.js`, `stores/documents.js`, `stores/folders.js`, `stores/cloudConnections.js`, `stores/topics.js`
|
|
- **Store tests (2):** `stores/__tests__/auth.test.js`, `stores/__tests__/cloudConnections.test.js`
|
|
- **Admin components (3):** `AdminUsersTab.vue`, `AdminQuotasTab.vue`, `AdminAiConfigTab.vue`, `AuditLogTab.vue`
|
|
- **Admin tests (3):** `AdminUsersTab.test.js`, `AdminQuotasTab.test.js`, `AdminAiConfigTab.test.js`
|
|
- **Settings components (2):** `SettingsAccountTab.vue`, `SettingsPreferencesTab.vue`
|
|
- **Settings tests (1):** `SettingsAccountTab.test.js`
|
|
- **Document components (3):** `DocumentCard.vue`, `DocumentPreviewModal.vue`, `DocumentView.vue`
|
|
- **Auth components (2):** `TotpEnrollment.vue`, `TotpEnrollment.test.js`
|
|
- **Cloud components (3):** `CloudCredentialModal.vue`, `CloudProviderTreeItem.vue`, `CloudFolderTreeItem.vue`
|
|
- **Layout (2):** `AppSidebar.vue`, `SettingsCloudTab.vue`
|
|
- **UI (1):** `SearchableModelSelect.vue`
|
|
- **Folder (1):** `FolderTreeItem.vue`
|
|
- **Views (6):** `CloudFolderView.vue`, `AccountView.vue`, `SharedView.vue`, `NewPasswordView.vue`, `PasswordResetView.vue`
|
|
|
|
## Blob-Download Pattern Consolidation
|
|
|
|
The 3 functions that duplicated auth-injection + 401-retry boilerplate were consolidated:
|
|
|
|
| Old function | Lines of retry boilerplate | After |
|
|
|---|---|---|
|
|
| `adminExportAuditLogCsv` (client.js:428-471) | ~15 lines | delegates to `fetchWithRetry()` |
|
|
| `adminDownloadDailyExport` (client.js:492-529) | ~15 lines | delegates to `fetchWithRetry()` |
|
|
| `fetchDocumentContent` (client.js:552-581) | ~15 lines | delegates to `fetchWithRetry()` |
|
|
|
|
The `fetchWithRetry()` helper in `utils.js` now owns the single implementation of this pattern.
|
|
|
|
## Decisions Made
|
|
|
|
- `request()` moved to `utils.js` (not `client.js`) to break the circular import: domain modules need `request()`, and `client.js` re-exports domain modules — these two directions cannot both exist in `client.js`
|
|
- Barrel pattern in `client.js` uses `export * from` for 7 domain modules plus explicit `export { fetchWithRetry, request } from './utils.js'` so utils functions are also available from the consumer-facing `client.js` surface
|
|
- `adminListDailyExports` keeps `request()` (returns JSON), only the download functions use `fetchWithRetry()`
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 1 - Bug] Fixed testAiConnection method from POST to GET with query params**
|
|
- **Found during:** Task 4 (barrel rewrite and test run)
|
|
- **Issue:** `testAiConnection` in `client.js` was sending POST with JSON body, but the existing test (`tests/api.spec.js`) expected GET with `?provider_id=...` query parameter — tests were failing on the base commit
|
|
- **Fix:** Changed `admin.js` implementation to `GET /api/admin/ai-config/test-connection?provider_id=<encoded>` matching the test contract (and what `getAiModels` does for consistency)
|
|
- **Files modified:** `frontend/src/api/admin.js`
|
|
- **Verification:** `npm test` — all 136 tests pass (was 2 failing before fix)
|
|
- **Committed in:** `02bf04c` (Task 4 commit)
|
|
|
|
---
|
|
|
|
**Total deviations:** 1 auto-fixed (Rule 1 — pre-existing bug in testAiConnection)
|
|
**Impact on plan:** Bug fix necessary for npm test to pass. No scope creep. The fix is correct — GET for a read-only connection test is more RESTful than POST.
|
|
|
|
## Issues Encountered
|
|
|
|
None beyond the pre-existing testAiConnection bug documented above.
|
|
|
|
## Known Stubs
|
|
|
|
None — this plan creates no stubs. All functions are fully implemented transport wrappers.
|
|
|
|
## Threat Flags
|
|
|
|
None — this plan introduces no new network endpoints, auth paths, file access patterns, or schema changes. All security-relevant patterns (bearer token from memory, lazy auth import, httpOnly cookie via credentials: 'include') were preserved verbatim from the original client.js.
|
|
|
|
## Next Phase Readiness
|
|
|
|
- Frontend API layer is fully decomposed and modular
|
|
- New API functions should go in the appropriate domain module, never directly in client.js
|
|
- The barrel re-export pattern means zero consumer edits are ever needed to add new domain modules
|
|
|
|
## Self-Check: PASSED
|
|
|
|
- All 9 files exist (verified: `ls frontend/src/api/`)
|
|
- All 4 task commits exist: `80d6f37`, `fd9188b`, `a895b18`, `02bf04c`
|
|
- `client.js` is 20 lines (< 25 requirement)
|
|
- 7 `export * from` lines confirmed in client.js
|
|
- 36 consumer files confirmed unchanged via `git diff --stat`
|
|
- `npm test`: 136/136 pass
|
|
- `npm run build`: exits 0
|
|
|
|
---
|
|
*Phase: 08-stack-upgrade-backend-decomposition*
|
|
*Completed: 2026-06-10*
|