FlashNotes

A simple flashcard app focused on quick card creation and distraction-free practice.

Technology Stack and Features

• 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.
• Frontend:
  • React with TypeScript, hooks, and Vite for a modern frontend stack.
    • Chakra UI for UI components.
    • Generated client for consuming the backend API.
  • Dexie.js and IndexedDB for offline/guest mode support and local data storage.
• 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.

Running GitHub Actions Locally

To test your GitHub Actions workflows locally before pushing to GitHub, you can use nektos/act. This tool allows you to simulate GitHub Actions workflows using Docker.

Here is a simple guide for how to do this here.

Setup Instructions

Backend Setup

1. Create a PostgreSQL database:

createdb <dbname>

2. 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=admin@example.com
FIRST_SUPERUSER_PASSWORD=<admin-password>
USERS_OPEN_REGISTRATION=true

3. Navigate to the backend directory:

cd backend

4. Make the prestart script executable:

chmod +x prestart.sh

5. Choose one of the following setup options:

Option 1: Quick Setup with uv

# 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

Option 2: Traditional Virtual Environment Setup

# 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

Frontend Setup

1. Install dependencies and start the development server:

cd frontend
pnpm install
pnpm run dev

Generate Frontend API Client (Only if backend API is updated)

The frontend uses a generated TypeScript client to communicate with the backend API. To update the client after making changes to the backend:

1. Activate the backend virtual environment:

cd backend
source .venv/bin/activate  # For Unix/Linux
# OR
.venv\Scripts\activate     # For Windows

2. Run the client generation script from the project root:

./scripts/generate_client.sh

API Documentation

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

Contributing

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!