Skip to content

mohsenkhosroanjam/FlashNotes

 
 

Repository files navigation

FlashNotes Logo

FlashNotes

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

Live Demo URL Discord

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:

Explore the API documentation at http://127.0.0.1:8000/docs.

Frontend (/frontend)

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 (/backend)

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

Setup Instructions

Backend Setup

  1. Create a PostgreSQL database:
createdb <dbname>
  1. 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
  1. Navigate to the backend directory:
cd backend
  1. Make the prestart script executable:
chmod +x prestart.sh
  1. 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
  1. 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:

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!

About

Resources

License

Contributing

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 68.3%
  • Python 29.2%
  • CSS 1.3%
  • Dockerfile 0.4%
  • HTML 0.3%
  • Shell 0.3%
  • Mako 0.2%