Architecture

IsotopeAI is one Node process with no runtime dependencies. It serves a pre-built React application, rewrites those bundles on the way out, and proxies data to your Supabase project.

One file, no dependencies #

server.mjs is around 10,000 lines and imports nothing outside the Node standard library plus two local modules. package.json lists zero dependencies and zero devDependencies, which is why install needs no build toolchain and cannot break from a transitive update.

Serve-time bundle patching #

The frontend in public/assets/ is a pre-built, minified Vite output. The server does not modify those files on disk. Instead, each patched bundle has a function that reads the file, performs exact string replacements, memoises the result and returns a Buffer:

function getPatchedCommunityBundle() {
  if (patchedCommunityBundle) return patchedCommunityBundle;   // memoised
  let raw = fs.readFileSync(COMMUNITY_BUNDLE_ABS, 'utf8');
  if (raw.includes(ANCHOR_FROM)) {
    raw = raw.replace(ANCHOR_FROM, ANCHOR_TO);
    console.log('[CommunityPatch] applied');
  } else {
    console.warn('[CommunityPatch] anchor not found');
    _criticalPatchFailures.push('community-anchor');   // surfaces as a UI banner
  }
  patchedCommunityBundle = Buffer.from(raw, 'utf8');
  return patchedCommunityBundle;
}

There are 23 patched bundles and around 52 individual patches. They fix upstream crashes, neutralise a demo-data gate, disable a circuit breaker that could lock all Supabase calls for five minutes, and add features such as group chat and the leaderboard tab.

Verifying patch health #

bash bin/isotope restart && sleep 6

# empty output means every anchor matched
grep -iE 'anchor not found|String not found' ~/.isotope/logs/server.log

# what did apply
grep -E '^\[[A-Za-z]+(Patch|CrashFix|KeyboardFix)' ~/.isotope/logs/server.log | sort -u

HTML script injection #

Every HTML response is rewritten. Scripts that must run before the app are placed before </head>; everything else is deferred to just before </body> so first paint is not blocked.

Service worker caching #

/assets/ is served cache-first, which is correct for content-hashed files but created a subtle failure: because bundles are patched at request time, editing a patch changed the response without changing the filename. A cached copy would be served indefinitely.

The cache name therefore includes a build token — a digest of VERSION plus the server.mjs modification time:

const CACHE_SUFFIX = APP_VERSION + '-' + APP_SHA.slice(0, 12) + '-' + BUILD_TOKEN;
const SHELL_CACHE   = 'isotope-local-shell-'   + CACHE_SUFFIX;
const RUNTIME_CACHE = 'isotope-local-runtime-' + CACHE_SUFFIX;

Any edit to a serve-time patch now rotates both caches on the next load. The live value is reported by /api/version as pwa_cache.

Supabase proxy #

/__supa/* forwards to your project. Escalation to the service-role key happens only for an authenticated admin:

const useServiceKey = ADMIN_MODE_READY && isAdminAuthed(req);

Every other caller is forwarded with their own Authorization header plus the anon key, so row-level security still applies.

Feature-to-Supabase map #

Which features actually reach Supabase, which are local-first, and which are local on purpose. The distinction matters: “local-first” means the feature works offline and syncs later; “local only” means it never touches the network and that is intended, not a gap.

The pattern worth noticing: everything a student produces while studying — tasks, sessions, subjects, habits, exams, timer state — is local-first and reaches Supabase only as a backup blob. Only community features genuinely require a connection, because they involve other people. That is why the app is usable on a phone with no signal.

SQL run order #

For a fresh project, in this order:

1. isotope-complete.sql — the whole schema. Idempotent, safe to re-run.

2. Compatibility migrations in sql/ — only when upgrading an older install.

3. sql/verify-security.sql — verification queries, not changes.

Upgrade-only patches, which a fresh install should skip:

Startup sequence #

1. Load and validate configuration

   .env then host environment. Exits on a malformed SUPABASE_URL.

2. Bind the port

   Listens on 0.0.0.0 so a phone on the same network can reach it.

3. Warm the patch cache

   All patchable bundles are patched and 11 are pre-gzipped, sequentially to avoid a CPU spike.

4. Ensure storage buckets

   Creates or reconciles the four buckets. Requires admin mode.

5. Run backfills

   Seeds satellite rows for existing users. Requires admin mode.