A simple flashcard app focused on quick card creation and distraction-free practice.
- Backend:
- FastAPI for the Python backend API.
- SQLModel for ORM-based SQL database interactions.
- Pydantic for data validation and settings management.
- PostgreSQL as the SQL database.
- FastAPI for the Python backend API.
- Frontend:
- Authentication:
- JWT (JSON Web Token) authentication.
- Guest Mode & Offline Support:
- Users can try the app instantly as a guest, with all data stored locally in the browser (IndexedDB).
- Guest Mode users can create, edit, and practice flashcards, but data will not sync across devices.
- Testing:
- Pytest for backend testing.
Explore the API documentation at http://127.0.0.1:8000/docs.
frontend/
├── public/ # Static assets and translations (i18n)
├── src/
│ ├── assets/ # Images, SVGs, and static media
│ ├── client/ # Generated API client (OpenAPI)
│ ├── components/ # Reusable UI components (cards, collections, stats, etc.)
│ ├── db/ # IndexedDB (Dexie.js) setup for offline/guest mode
│ ├── data/localDB/ # Local DB logic for guest/offline mode (CRUD, stats, etc.)
│ ├── hooks/ # Custom React hooks (auth, data fetching, etc.)
│ ├── repositories/ # Data access layer (API/local switch for cards, collections, stats)
│ ├── routes/ # Application routes (pages, layouts)
│ ├── services/ # Business logic for cards, collections, practice, stats
│ ├── utils/ # Utility functions (auth, stats, etc.)
│ └── main.tsx # App entry point
├── package.json # Frontend dependencies and scripts
├── pnpm-lock.yaml # Lockfile for reproducible installs
├── tsconfig*.json # TypeScript configuration
├── vite.config.ts # Vite build configuration
└── index.html # Main HTML template
backend/
├── src/
│ ├── api/ # FastAPI route definitions
│ ├── core/ # Core logic (auth, config, security)
│ ├── db/ # Database models and access (SQLAlchemy)
│ ├── schemas/ # Pydantic models (request/response)
│ ├── services/ # Business logic (users, flashcards, etc.)
│ └── main.py # FastAPI app entry point
├── tests/ # Backend tests (pytest)
├── pyproject.toml # Python dependencies and project config
├── uv.lock # Poetry/uv lockfile for reproducible installs
├── Dockerfile # Production Docker build
├── Dockerfile.pip # Alternative Docker build (pip)
├── entrypoint.sh # Docker entrypoint script
├── prestart.sh # Pre-start script (migrations, etc.)
└── alembic.ini # Alembic DB migration config
- Create a PostgreSQL database:
createdb <dbname>
- Set up environment variables in
backend/.env
:
PROJECT_NAME=FlashNotes
DOMAIN=localhost
POSTGRES_SERVER=localhost
POSTGRES_USER=<your-username>
POSTGRES_PASSWORD=<your-password>
POSTGRES_DB=<dbname>
FIRST_SUPERUSER=[email protected]
FIRST_SUPERUSER_PASSWORD=<admin-password>
USERS_OPEN_REGISTRATION=true
- Navigate to the backend directory:
cd backend
- Make the prestart script executable:
chmod +x prestart.sh
- Choose one of the following setup options:
# Install dependencies and run migrations
uv run ./prestart.sh # Run ./prestart.sh to run db migrations
# Start the development server
uv run uvicorn src.main:app --reload
# Create and activate virtual environment
uv venv .venv
source .venv/bin/activate
# Install dependencies
uv sync
# Run migrations
./prestart.sh
# Start the development server
uvicorn src.main:app --reload
The backend server will be available at http://127.0.0.1:8000
- Install dependencies and start the development server:
cd frontend
pnpm install
pnpm run dev
The frontend uses a generated TypeScript client to communicate with the backend API. To update the client after making changes to the backend:
- Activate the backend virtual environment:
cd backend
source .venv/bin/activate # For Unix/Linux
# OR
.venv\Scripts\activate # For Windows
- Run the client generation script from the project root:
./scripts/generate_client.sh
Once the backend is running, access the interactive API documentation at:
- ReDoc: http://127.0.0.1:8000/redoc
- Swagger UI: http://127.0.0.1:8000/docs
We welcome contributions! Please see our Contributing Guidelines for details on how to get started, report bugs, suggest enhancements, and submit pull requests. Feel free to join our Discord for questions and discussions!