Lexync
Lexync is a private language-learning system for deliberate capture in a Chromium extension and offline practice on Android.
Requirements
- Node.js 22.20.0
- pnpm 10.30.3
- Docker
- JDK 17
- Android SDK 36
Workspace commands
pnpm install
pnpm check
pnpm test
pnpm build
pnpm android:test
pnpm android:build
Run Supabase, the web application, and the WXT extension together with pnpm dev. Run only the web application with pnpm dev:web or only the extension with pnpm dev:extension.
Local backend and extension
Start Supabase and apply all migrations with:
pnpm backend:start
pnpm backend:reset
Copy .env.example to .env.local and provide the Supabase URL, browser-safe publishable key, and web URL. Secret and service-role keys must never use a WXT_PUBLIC_ variable.
Migrations reach the deployed Supabase project through the Push database migrations workflow, with pnpm db:push kept only as a break-glass. See docs/database-migrations.md.
pnpm test starts and resets the local Supabase project, runs the focused ownership-policy tests, builds every JavaScript/TypeScript workspace, and runs Playwright. Stop the local services with pnpm backend:stop when they are no longer needed.
Email and password authentication
The extension supports account creation, email and password sign-in, email confirmation, and password recovery through Supabase Auth. No external OAuth provider credentials are required.
Local Supabase disables email confirmation so deterministic tests can create authenticated Learners immediately. In a hosted project, enable email confirmation and add the web callback URL to the allowed Auth redirect URLs:
https://your-web-host/auth/callback
Configure a production SMTP provider before sending confirmation and password recovery emails to real users.
For the hosted web app, configure NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY in the deployment environment, using the same browser-safe Supabase values.
Learning Material preparation and Dynamic Lesson creation need three more server-side variables in that same environment, or both fail at request time:
LEXYNC_EMBEDDING_PROVIDER=gemini
LEXYNC_GENERATION_PROVIDER=gemini
LEXYNC_LANGUAGE_DETECTION_PROVIDER=gemini
GEMINI_API_KEY=your-key
Each provider variable also accepts a keyless value for tests — deterministic for embeddings and generation, script for language detection.
Android
The native Kotlin and Jetpack Compose application is in apps/android. Configure its browser-safe Supabase connection in ~/.gradle/gradle.properties:
lexync.supabase.url=https://your-project.supabase.co
lexync.supabase.publishableKey=your-publishable-key
For the local Supabase stack, use http://10.0.2.2:54321 from the Android emulator and the publishable key printed by pnpm backend:start. Never configure a secret or service-role key in the Android build.
Build the debug APK with pnpm android:build. Run the JVM contract tests with pnpm android:test. Seed the local acceptance account with pnpm android:seed. With an emulator running, compile and run the Room and Compose journeys with:
cd apps/android
./gradlew connectedDebugAndroidTest \
-Plexync.supabase.url=http://10.0.2.2:54321 \
-Plexync.supabase.publishableKey=your-local-publishable-key \
-Pandroid.testInstrumentationRunnerArguments.lexyncTestEmail=android-learner@example.test \
-Pandroid.testInstrumentationRunnerArguments.lexyncTestPassword=Lexync-Android-test-37
The synchronized library is replaced in one Room transaction and remains available after an offline restart. Failed or invalid snapshots leave the previous complete library intact.
Continuous integration
Pull requests and updates to main run the JavaScript, browser, Supabase, and Android validation lanes. Successful runs retain the deterministic Chromium extension ZIP and installable Android debug APK. Failed runs retain the available Playwright, emulator, and local Supabase diagnostics. The stable required check is Aggregate; the active main protection ruleset currently requires zero approving reviews while this repository has one maintainer. Increase required_approving_review_count to 1 when a second maintainer joins.
The iPhone requirements remain in SPEC.md, but iPhone delivery is paused. Xcode builds and XCUITest do not run in continuous integration and do not block pull requests until that roadmap resumes.
