https://github.com/kirill-markin/flashcards-open-source-app
Open-source, offline-first Anki alternative for iOS and web with FSRS spaced repetition, local-first sync, and a self-hostable AWS backend.
https://github.com/kirill-markin/flashcards-open-source-app
anki-alternative aws edtech education flashcards fsrs indexeddb ios learning local-first offline-first postgresql react self-hosted spaced-repetition sqlite swiftui sync typescript web
Last synced: 3 months ago
JSON representation
Open-source, offline-first Anki alternative for iOS and web with FSRS spaced repetition, local-first sync, and a self-hostable AWS backend.
- Host: GitHub
- URL: https://github.com/kirill-markin/flashcards-open-source-app
- Owner: kirill-markin
- License: mit
- Created: 2026-03-02T07:17:34.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T08:09:41.000Z (3 months ago)
- Last Synced: 2026-03-31T08:50:25.060Z (3 months ago)
- Topics: anki-alternative, aws, edtech, education, flashcards, fsrs, indexeddb, ios, learning, local-first, offline-first, postgresql, react, self-hosted, spaced-repetition, sqlite, swiftui, sync, typescript, web
- Language: TypeScript
- Homepage: https://flashcards-open-source-app.com/
- Size: 8.85 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Flashcards Open Source App
Flashcards are a simple study format: the front side shows a question or prompt, and the back side shows the answer. People use them to study languages, facts, definitions, code, and other material they want to remember. This project is an open-source Anki-like flashcards app focused on iOS, Android, web, and offline-first sync.
Open-source offline-first flashcards app for iOS, Android, and web.
## Clients
- iOS app in `apps/ios`
- Android app in `apps/android`
- Web client in `apps/web`
- AI agents support through the external agent API: [https://api.flashcards-open-source-app.com/v1/](https://api.flashcards-open-source-app.com/v1/)
## Features
- Offline-first: browser local database on web, SQLite on iOS and Android
- Auto-sync: clients write locally first and sync with the backend when online
## Release Gates
Production delivery on `main` now uses one GitHub Actions release orchestrator:
- it detects which areas changed
- deploys AWS when `api`, `auth`, `backend`, `web`, `infra`, `db`, or deploy scripts changed
- runs the web Playwright live smoke after deploy
- keeps the new AWS release only if the smoke passes
- rolls the whole AWS runtime back to the previous retained AWS SHA when the smoke fails and the release did not include DB migrations
- fails loudly and requires fix-forward when the smoke fails after DB migrations
Native client gates still use native stacks:
- iOS uses XCTest and XCUITest, including the stateful live smoke in [`apps/ios/Flashcards/FlashcardsUITests/LiveSmokeUITests.swift`](apps/ios/Flashcards/FlashcardsUITests/LiveSmokeUITests.swift), and the main orchestrator waits on the matching Xcode Cloud checks for the same SHA when `apps/ios` changed
- Android uses JUnit plus native Compose instrumentation, including the stateful live smoke in [`apps/android/app/src/androidTest/java/com/flashcardsopensourceapp/app/LiveSmokeTest.kt`](apps/android/app/src/androidTest/java/com/flashcardsopensourceapp/app/LiveSmokeTest.kt); pull requests use the standalone Android CI entry workflow, and the main orchestrator runs the same reusable Android CI before publishing to Google Play
- Web uses targeted Vitest checks and Playwright, including the stateful live smoke in [`apps/web/e2e/live-smoke.spec.ts`](apps/web/e2e/live-smoke.spec.ts)
The repository does not aim for exhaustive test coverage, and we do not add unit tests for every small detail by default. We allow targeted integration or module-boundary tests when they verify a real interaction, but the most trusted checks are the native/browser live smoke flows that exercise the real app on a simulator, emulator, managed device, or deployed environment closest to production.
After every push to `main`, watch the single main release orchestrator until it either retains the AWS release, rolls it back, or fails clearly on a non-rollbackable migration path.
## Card scheduling
- Review scheduling uses FSRS-6 with pinned default weights
- The full scheduler is implemented in backend and iOS and must stay behaviorally identical
- The web app mirrors the scheduler data contract and review flow, but does not contain a third FSRS implementation
- Cards appear in review when they are due: `due_at <= now()`
- Detailed scheduling rules live in [`docs/fsrs-scheduling-logic.md`](docs/fsrs-scheduling-logic.md)
## Setup Docs
- [iOS local setup](docs/ios-local-setup.md)
- [iOS CI/CD](docs/ios-ci-cd.md)
- [Android CI/CD](docs/android-ci-cd.md)
- [Web app notes](apps/web/README.md)
- [Backend and web deployment](docs/backend-web-deployment.md)
- [More architecture details](docs/architecture.md)
Android CI/CD setup uses separate GitHub repository variables for Google Cloud and Firebase Test Lab. The required variable names and the helper sync script are documented in [`docs/android-ci-cd.md`](docs/android-ci-cd.md).
## Review Demo Accounts
The optional `DEMO_EMAIL_DOSTIP` auth setting only enables insecure instant sign-in for listed review/demo emails in the `example.com` domain. For deployed auth, keep the allowlist as normal deploy config and keep the shared demo password in AWS Secrets Manager.
If review/demo access is enabled, create the matching `@example.com` Cognito users manually and keep their emails and shared password aligned with the deployed allowlist and demo password secret. The intended setup flow is: keep `DEMO_EMAIL_DOSTIP` and `DEMO_PASSWORD_DOSTIP` in the local root `.env`, run `bash scripts/setup-auth-secrets.sh --region `, then run `bash scripts/setup-github.sh`. We intentionally keep Cognito user creation manual instead of adding an automated provisioning script for these insecure review-only accounts.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Author
- [Kirill Markin](https://github.com/kirill-markin)