Skip to content

README.md

Latest commit

 

History

History
358 lines (257 loc) · 7.88 KB

README.md

File metadata and controls

358 lines (257 loc) · 7.88 KB

IsotopeAI logo

IsotopeAI

A study app you run on your own device.

Version Docs

Animated docs · Install · Sync safety · Admin proof · Screenshots

IsotopeAI landing page screenshot

It includes:

  • Focus timer
  • Tasks and subjects
  • Study sessions and stats
  • Habits, exams, tests, and mock tests
  • Optional Supabase login, backup, restore, and community features

Start here:

Pick Your Device

Android with Termux

Install Termux from F-Droid or GitHub, not the old Play Store app.

bash <(curl -fsSL https://raw.githubusercontent.com/Suydev/isotope-code/main/install-termux.sh)

After install:

isotope start

Open:

http://127.0.0.1:3000

Linux

git clone https://github.com/Suydev/isotope-code.git
cd isotope-code
bash setup.sh
isotope start

macOS

Install Git and Node.js first if you do not have them.

git clone https://github.com/Suydev/isotope-code.git
cd isotope-code
bash setup.sh
isotope start

Windows

Use PowerShell:

git clone https://github.com/Suydev/isotope-code.git
cd isotope-code
.\install.ps1

Or use Command Prompt:

git clone https://github.com/Suydev/isotope-code.git
cd isotope-code
setup.bat

Then open:

http://127.0.0.1:3000

What Setup Does

Setup checks for:

  • Node.js 18 or newer
  • npm
  • Git
  • .env
  • required scripts

It then installs the isotope command.

Useful Commands

isotope start              # start the app
isotope stop               # stop the app
isotope restart            # restart the app
isotope open               # open in browser
isotope update             # update from GitHub
isotope status             # show status
isotope doctor             # find problems
isotope logs               # show logs
isotope repair             # repair install
isotope reinstall-widgets  # Android Termux widget shortcuts

Supabase Setup

The app works best with your own Supabase project.

You need Supabase for:

  • login
  • sync
  • cloud backup
  • restore on a new device
  • avatars
  • groups and community features

Steps:

  1. Create a free project at https://supabase.com
  2. Open SQL Editor.
  3. Paste and run isotope-complete.sql.
  4. Create these Storage buckets if they do not already exist:
    • avatars
    • user-content
    • notes
  5. Copy your Project URL and anon key.
  6. Put them in .env.

Example:

SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_ANON_KEY=your-anon-public-key
PORT=3000
ENABLE_ADMIN_MODE=false

Do not put a service-role key in the browser.

Do not commit .env.

Setup Env Rules

  • .env is the preferred runtime env file.
  • If .env is missing and yeh.env exists, setup copies yeh.env to .env.
  • If ISOTOPE_ENV_FILE is set, setup reads that file, copies it to .env, and uses the copied values.
  • Existing SUPABASE_URL, SUPABASE_ANON_KEY, and ENABLE_ADMIN_MODE values are preserved.
  • If ENABLE_ADMIN_MODE is missing, setup writes ENABLE_ADMIN_MODE=false.

Safe Cloud Backup

The app now uses one backup system.

Main backup:

{userId}/backups/latest.json

Backup history:

{userId}/backups/history/{timestamp}-{hash}.json

Cloud mirror:

{userId}/cloud-snapshot/latest.json

Old folders are still read for safety:

{userId}/imports/latest.json
{userId}/exports/latest.json
{userId}/cloud-snapshot/latest.json

Important rule:

If this device is empty and cloud has a richer backup, upload is blocked. The app must restore cloud data first.

Blocked code:

BLOCKED_EMPTY_OVERWRITE

Admin Mode

Admin mode is optional.

Use it only on your own machine.

ENABLE_ADMIN_MODE=true
ADMIN_SECRET=<long-random-secret>
ADMIN_EMAIL=<your-email@example.com>

Add SUPABASE_SERVICE_ROLE_KEY only in your private .env when you need admin repair tools.

Open:

http://127.0.0.1:3000/__admin

Useful admin pages:

  • /__admin/verify
  • /__admin/sync
  • /__admin/storage
  • /__admin/roles
  • /__admin/patch

Backup Repair Commands

Dry-run first:

node scripts/repair-user-backup.mjs --user <user-id> --dry-run

Apply only after the dry-run looks safe:

node scripts/repair-user-backup.mjs --user <user-id> --apply

Check backups:

node scripts/validate-backup-files.mjs --user <user-id>

Preview cleanup:

node scripts/validate-storage-cleanup.mjs --user <user-id> --dry-run

Troubleshooting

Problem Try this
App does not open isotope start then open http://127.0.0.1:3000
Port is busy isotope stop or set PORT=3001 in .env
Login fails Check SUPABASE_URL and SUPABASE_ANON_KEY
Sync is blocked Restore the cloud backup first
Storage permission error Re-run isotope-complete.sql
Android widget is missing isotope reinstall-widgets
Update failed isotope doctor, then isotope repair

Runtime Login Bridge And Cache Troubleshooting

Do not test browser globals in the Node REPL. Node has no window, so typeof window.__isoLogin is not a valid Node check.

Use the browser console on http://127.0.0.1:3000/auth:

typeof window.__isoLogin
typeof window.__isoUp

Both should return "function".

Use the Node smoke test when a browser is not available:

npm run test:auth-bridge

To prove the configured Supabase project can perform the Storage-backed sync path end to end:

npm run test:supabase-sync

If a stale PWA or browser cache is serving old runtime files, clear runtime caches from the browser console:

caches.keys().then(keys => Promise.all(keys.map(k => caches.delete(k)))).then(() => location.reload())

If the top-right cloud sync button says Authentication required, the browser is not holding a valid Supabase session even if the app shell still looks logged in. Sign out, sign in again through /auth, then run:

typeof window.__isoGetValidJwt

For Contributors

Before changing sync, backup, auth, or SQL:

node --check server.mjs
node --check server/backup-manager.mjs
node --check public/sync/backup-normalizer.js
node --check public/sync/local-data-adapter.js
node scripts/validate-backup-files.mjs --user <user-id>
node scripts/repair-user-backup.mjs --user <user-id> --dry-run
npm run assets:compare

Rules:

  • Do not commit .env.
  • Do not expose service-role keys to the frontend.
  • Do not weaken RLS to hide a bug.
  • Do not let empty local data overwrite rich cloud data.
  • Do not replace compiled assets from the live site unless the asset report proves the same chunk graph is available.
  • Keep docs simple and true.

License

MIT. See LICENSE.