10xCards

Project name

10xCards

Project description

10xCards is a web application for creating and learning flashcards (front/back) using AI-assisted generation and the FSRS spaced-repetition algorithm.

The MVP focuses on:

• Fast flashcard generation from pasted text
• Review + editing of generated cards (accept/reject + multi-select)
• Daily study sessions (FSRS)
• AI cost control (token limits)

Table of contents

• Project name
• Project description
• Tech stack
• Getting started locally
• Available scripts
• Project scope
• Project status
• License
• Contributing

Tech stack

• Frontend: Astro 5 + React 19 + TypeScript 5
• UI: Tailwind CSS 4 + shadcn/ui (Radix primitives)
• Backend: Supabase (PostgreSQL + Auth + SDK)
• AI: OpenRouter (OPENROUTER_API_KEY)
• Hosting/infra: DigitalOcean (Docker image deployment)
• Tooling: ESLint + Prettier + Husky + lint-staged
• Testing:
  • Unit & integration: Vitest (Vite-native, ESM, TypeScript, watch mode, coverage v8/istanbul); mocks: vi.fn() / vi.mock(), MSW (Mock Service Worker) for API/OpenRouter
  • E2E: Playwright (Chromium/Firefox/WebKit), tests against astro dev or astro preview; auth via storage state, parallel projects

High-level architecture

flowchart LR
  U[User] -->|Browser| FE[Astro 5 + React 19 UI]
  FE -->|SSR / API routes| APP[Astro Node adapter - standalone]
  APP -->|Auth + DB| SB[(Supabase\nPostgreSQL + Auth)]
  APP -->|AI generation| OR[OpenRouter API]
  SB -->|stores| DATA[Flashcards, tags, decks,\nFSRS scheduling, token usage]

Loading

Getting started locally

Prerequisites

• Node.js: 22.14.0 (see .nvmrc)
• npm: comes with Node.js

Setup

1. Install dependencies:

npm install

2. Create a local .env file (or export env vars in your shell) with at least:

SUPABASE_URL=...
SUPABASE_KEY=...
OPENROUTER_API_KEY=...

Notes:

• SUPABASE_URL / SUPABASE_KEY are required to connect to Supabase.
• OPENROUTER_API_KEY is required for AI flashcard generation.

3. Run the dev server (defaults to port 3000):

npm run dev

4. Build and run the production build locally:

npm run build
npm run preview

Available scripts

Development

• npm run dev: start Astro dev server
• npm run build: create a production build
• npm run preview: preview the production build
• npm run astro: run the Astro CLI

Code Quality

• npm run lint: run ESLint across the repo
• npm run lint:fix: run ESLint with auto-fixes
• npm run format: format files with Prettier

Testing

• npm run test: run unit tests in watch mode
• npm run test:run: run unit tests once
• npm run test:ui: run unit tests with UI
• npm run test:coverage: run unit tests with coverage report
• npm run test:e2e: run E2E tests with Playwright
• npm run test:e2e:ui: run E2E tests with Playwright UI
• npm run test:e2e:debug: debug E2E tests
• npm run test:e2e:codegen: generate E2E tests with Playwright codegen

See TESTING.md for setup, running, and writing tests (src/test/, e2e/, npm run test:run, npm run test:e2e). Quick reference: TESTING-CHEATSHEET.md.

Project scope

MVP hypothesis & success criteria

• Hypothesis: users can generate a study-ready set of flashcards without manually writing most cards.
• MVP success: ≥ 75% acceptance rate for AI-generated flashcards (saved, including after edits).
• Failure: acceptance rate < 75% despite prompt/limit iterations.

MVP priorities

• P0 (must-have):
  • AI flashcard generation + accept/edit workflow
  • Anti-hallucination via sources extracted from inputText
  • Daily FSRS session
  • AI cost controls (token limits)
• P1:
  • Decks (manual + dynamic)
  • Search
• P2 (out of MVP scope):
  • Offline mode
  • Monitoring (Prometheus/Grafana)
  • Full history/versioning
  • Mermaid/diagrams inside user content (MVP forbids Mermaid in flashcard Markdown)

Functional scope (high level)

• Auth: Google OAuth, sessions with TTL
• Flashcards:
  • Markdown content (no HTML)
  • Fields: front, back, tags, difficulty, sources, origin, timestamps, deletedAt
  • One-level rollback stored in DB, TTL = 24h since last edit; each edit overwrites previous version and resets TTL
• Tags: managed by admin; users can only search/select (no user-created tags)
• Decks:
  • Manual decks: many-to-many
  • Dynamic decks: tag-based filters; materialized as a snapshot at the start of the daily FSRS session
• AI limits:
  • Limits on input text size, max cards per batch, max front/back length
  • Per-user/day token counter with a fixed daily window, reset at 00:00 UTC
  • Block requests when estimated usage exceeds the limit
• Sources (anti-hallucination): excerpts must match the input text, with startOffset/endOffset
• Search: by front + tags
• FSRS:
  • Ratings: Again / Hard / Good / Easy
  • Admin-configurable daily card limit
  • Deterministic unit tests for scheduling correctness + snapshotting before/after session
  • Admin-only schedule reset for debugging
• Admin panel: UI languages, generator languages, character/token limits, max cards/batch, tag list, session limits
• Delete:
  • Soft-delete flashcards
  • Hard-delete account + all user data

Project status

• Current state: early MVP development (base Astro/React/Tailwind setup is present).
• Primary objective: validate the MVP hypothesis by achieving ≥ 75% AI flashcard acceptance rate.

License

No LICENSE file is present in this repository. Until a license is added, treat the code as All rights reserved.

Contributing

• Follow the repo conventions: Astro 5 + React 19 + TypeScript 5 + Tailwind 4, with ESLint/Prettier formatting.
• Use the scripts: run npm run lint (or npm run lint:fix) and npm run format before opening a PR.
• Keep changes scoped: prefer small PRs that map to a single feature/requirement from the PRD.

Additional documentation

• Testing: TESTING.md — setup, unit (Vitest) and E2E (Playwright), src/test/, e2e/, commands. Quick reference: TESTING-CHEATSHEET.md.
• PRD: /.ai/prd.md
• Tech stack notes: /.ai/tech-stack.md