Skip to content

Commit e09d1ae

Browse files
hattonhatton
committed
supabase migration thoughts
1 parent 1b753c7 commit e09d1ae

1 file changed

Lines changed: 119 additions & 0 deletions

File tree

‎supabase-migration-thoughts.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Supabase Migration Plan: Estimated Scope of Work
2+
3+
This is a snapshot of ongoing conversation with LLMs with access to this codebase. The purpose is to help us think about the task, it's not anything near to an actual plan.
4+
5+
## Things we do know
6+
7+
* We will be migrating this client code from Parse Server to a SQL database on Supabase.
8+
* We cannot yet use Supabase native auth. We will need to continue to use Firebase.
9+
* How the cloud functions and DB itself are migrated is not in scope here, that's handled elsewhere.
10+
* We do not need to have these two system running simultaneously in production.
11+
* We do not need to gradually migrate. The legacy code is not under active development.
12+
* We will standardize on the official Supabase JS SDK (`@supabase/supabase-js`) for all database access and authentication.
13+
14+
## Known unknowns
15+
16+
It is not clear yet how much effort should go into code base preparation, including:
17+
* isolating all existing ParseServer-specific code,
18+
* creating an anti-corruption layer with (intially) a ParseServer impelementation, against which unit tests can run
19+
* adding new tests to lock down current behavior
20+
21+
---
22+
23+
### BLORG Frontend Application Refactoring
24+
25+
1. **Connection and Authentication (SDK):**
26+
- Create `src/data/supabaseClient.ts` to initialize and export a configured Supabase client.
27+
- Replace `connectParseServer()` with Supabase auth flows (signInWithIdToken or signInWithOAuth as appropriate) and session handling via the SDK.
28+
- Files to change:
29+
- `src/connection/ParseServerConnection.ts` — removed/replaced.
30+
- `src/authentication/firebase/firebase.ts` — replace `connectParseServer` usage with Supabase auth calls.
31+
- `src/authentication/authentication.ts` — replace logout with `supabase.auth.signOut()`.
32+
33+
2. **Queries and Mutations (SDK):**
34+
- Replace all REST calls and `ParseServerConnection` imports with repository functions that use the SDK: `supabase.from('table').select(...)`, `.insert(...)`, `.update(...)`, and RPC calls with `supabase.rpc('fn', params)`.
35+
- Files to change:
36+
- `src/connection/LibraryQueries.ts`
37+
- `src/connection/LibraryQueryHooks.ts`
38+
- `src/connection/LibraryUpdates.ts`
39+
- `src/connection/ApiConnection.ts`
40+
- `src/components/BulkEdit/BulkChangeFunctions.ts`
41+
- `src/components/BookDetail/ReportDialog.tsx`
42+
43+
3. **Data Model Mapping:**
44+
- Update functions that map DB responses to frontend models to reflect SQL row shapes.
45+
- Files to change:
46+
- `src/model/Book.ts` — replace `createBookFromParseServerData` and `finishCreationFromParseServerData` with equivalents for Supabase rows.
47+
- `src/model/ArtifactVisibilitySettings.ts` — replace `createFromParseServerData` usages.
48+
- `src/export/freeLearningIO.ts` — update to call the new `createBookFromSupabaseRow`.
49+
50+
4. **Repository Isolation (SDK under the hood):**
51+
- Create small data-access modules to keep SDK usage localized:
52+
- `src/data/booksRepo.ts` — `getBook`, `searchBooks`, `updateBook`, `updateArtifactVisibility`, etc.
53+
- `src/data/usersRepo.ts` — auth helpers/user profile.
54+
- `src/data/adminRepo.ts` — staff/bulk edit mutations.
55+
- Refactor callers listed above to use these repos instead of direct SDK calls.
56+
57+
---
58+
59+
60+
### Test Coverage and Pre‑Migration Hardening
61+
62+
Goal: lock in current behavior so the migration can be validated quickly and safely on the branch.
63+
64+
What exists now (indicative sample):
65+
- `src/connection/LibraryQueryHooksFast.test.ts` — unit tests for building Parse query objects (offline, no network).
66+
- `src/connection/LibraryQueryHooks.test.ts` — networked tests against a Parse unit-test server using axios to verify end‑to‑end search semantics (quoted terms, tag facets, uploader/copyright).
67+
- `src/connection/sorting.test.ts` — sorting behavior of titles and locale nuances.
68+
- `src/connection/SplitString.test.ts` — parsing query strings into parts.
69+
- `src/components/ArtifactHelper.test.ts` — URL parsing for artifact names.
70+
- `src/model/Book.test.ts` — feature normalization (e.g., quiz implies activity).
71+
- `src/model/SpecialSearch.test.ts` — special search parsing.
72+
73+
Gaps and risks relative to Supabase:
74+
- Query-builder semantics will change: `constructParseBookQuery` tests lock in Parse JSON, not desired SQL filters or repo inputs/outputs.
75+
- Networked Parse unit tests will be invalid after migration; we need equivalents that assert outputs (datasets returned), not Parse-specific endpoints.
76+
- Data mapping: no tests currently assert that `createBookFromParseServerData` produces stable `Book` objects from backend rows.
77+
- Auth/session flows have no explicit tests.
78+
79+
Recommended pre‑migration work (on the branch before large refactors):
80+
1) Introduce repository‑level contract tests (backend‑agnostic)
81+
- Create tests that call repo functions and assert returned arrays/objects, not transport format.
82+
- New tests (suggested files):
83+
- `src/data/__tests__/booksRepo.contract.test.ts`
84+
- getBook(id) returns minimal shape { id, title, tags, updatedAt }
85+
- searchBooks(q) respects quoted terms, tag facets, uploader, publisher filters
86+
- updateBook(id, patch) persists and is observable on a subsequent read
87+
- `src/data/__tests__/adminRepo.contract.test.ts` (only for admin flows used by BulkEdit)
88+
- Temporarily wire these tests to current Parse implementation through a thin adapter so they pass now; then swap the adapter to Supabase during migration.
89+
90+
2) Freeze critical behaviors with pure unit tests
91+
- Replace Parse‑specific query JSON assertions with input/output tests around new helpers:
92+
- Add `src/data/query/filters.test.ts` covering:
93+
- parsing search string to structured filter (quoted phrases, facets like `topic:`, `region:`, `bookshelf:`)
94+
- level filters (`level:1`, `level:empty`) logic
95+
- Add mappers tests:
96+
- `src/model/Book.mapper.test.ts` for `createBookFromSupabaseRow` (to be introduced) ensuring stable `Book` object creation and date parsing.
97+
98+
3) Guard UI‑visible behavior
99+
- Keep existing tests that validate sorting and artifact URL behavior (already backend‑agnostic).
100+
- Add a minimal test for `getBestBookTitle`/`parseAllTitles` behavior using JSON from `allTitles` to ensure unchanged results.
101+
102+
4) Test utilities and setup
103+
- Add a tiny test data factory for books to reduce duplication in repo tests.
104+
- Ensure Vitest config supports node + jsdom where needed (already `environment: "jsdom"`; repo tests can run under node if desired via per‑file override).
105+
106+
Removal/transition plan for Parse‑specific tests
107+
- Mark `src/connection/LibraryQueryHooks.test.ts` as legacy and keep until Supabase repos pass the contract tests.
108+
- Replace `constructParseBookQuery` unit tests with `filters.test.ts` that assert our own filter struct rather than Parse JSON.
109+
110+
Minimal acceptance to proceed with migration work
111+
- Contract tests for `booksRepo` pass against current backend adapter.
112+
- Mapper tests for `Book` pass using sample rows.
113+
- Sorting/URL/helper tests continue to pass unchanged.
114+
115+
---
116+
117+
### Summary of Effort
118+
119+
The migration work remains concentrated in `src/connection`, `src/model`, and `src/authentication`, with new `src/data/*` modules to isolate SDK usage. The largest tasks are translating queries/mutations to SDK calls and remapping data models to the SQL schema.

0 commit comments

Comments
 (0)