OpenPep

A cross-platform desktop application built with Electron, React + TypeScript, and a bundled FastAPI backend.

Replace {owner}/{repo} in the badge URLs above with your GitHub username and repository name.

Tech Stack

Layer	Technology
Desktop shell	Electron 35
Frontend	React 19, TypeScript, Vite 6
UI	TailwindCSS 4, shadcn/ui
Backend	FastAPI, SQLAlchemy 2 (async), aiosqlite
Migrations	Alembic
Bundler	PyInstaller

Prerequisites

• Node.js 20+
• Python 3.11+
• npm

Quick Start

1. Clone and install frontend dependencies

git clone https://github.com/{owner}/{repo}.git
cd OpenPep
npm install

2. Set up the Python backend

cd backend
python3 -m venv venv

# macOS / Linux
source venv/bin/activate

# Windows
venv\Scripts\activate

pip install -r requirements.txt

3. Configure environment variables

cp .env.example .env
# Edit .env and set APP_SECRET_KEY, VITE_APP_SECRET, and DATABASE_URL

4. Run database migrations

# From backend/ with venv active
alembic upgrade head

5. Start development

# From the project root, with backend venv active
npm run dev

This starts the FastAPI backend and the Electron app with hot reload simultaneously.

Start the backend manually (from backend/ with venv active)

uvicorn app.app:app --host 127.0.0.1 --port 8000

Add --reload for auto-reload on file changes during development.

Once running, API docs are available at:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

Environment Variables

Variable	Description	Default
APP_SECRET_KEY	Shared secret validated by the backend on every request	change-this-in-production
VITE_APP_SECRET	Same secret, embedded in the Electron frontend at build time	""
DATABASE_URL	SQLAlchemy connection URL	sqlite+aiosqlite:///./app.db

Database Migrations

Models live in backend/app/db/models/. Register each new model in backend/app/db/models/__init__.py so Alembic detects it.

# Generate a migration after adding/changing a model
alembic revision --autogenerate -m "describe the change"

# Apply pending migrations
alembic upgrade head

# Roll back one migration
alembic downgrade -1

Testing

Backend

cd backend
pip install -r requirements-dev.txt
pytest --cov=app --cov-report=term-missing tests/

Frontend

npm test

Production Build

Build for the current platform:

npm run build

Output is placed under release/{version}/. See the Release workflow to produce signed installers for all three platforms via GitHub Actions.

Project Structure

OpenPep/
├── electron/              # Electron main process + preload
├── src/                   # React frontend
│   ├── components/        # Shared UI components
│   ├── hooks/             # Custom hooks (useAxios, …)
│   ├── pages/             # Route-level page components
│   └── routes.tsx
├── backend/
│   ├── app/
│   │   ├── api/           # FastAPI routers
│   │   ├── config/        # Config and env vars
│   │   └── db/
│   │       ├── database.py   # Engine, session, Base
│   │       └── models/       # SQLAlchemy models
│   ├── alembic/           # Migration scripts
│   ├── tests/             # pytest test suite
│   ├── alembic.ini
│   ├── main.spec          # PyInstaller spec
│   ├── requirements.txt
│   └── requirements-dev.txt
└── .github/workflows/
    ├── ci.yml             # Lint, security, coverage
    └── release.yml        # Multi-platform packaging

CI/CD

CI (ci.yml) — runs on every push and pull request

Job	Tool	Scope
lint	ESLint + flake8	Frontend TS/TSX, backend Python
security	Bandit	Backend Python (SARIF upload)
coverage	pytest-cov + Vitest	Backend unit tests, frontend unit tests

Release (release.yml) — runs on v* tags or manual dispatch

Builds the PyInstaller backend binary and Electron installer natively on each platform:

Platform	Runner	Output
Windows	windows-latest	NSIS installer (.exe)
macOS	macos-latest	Disk image (.dmg)
Linux	ubuntu-latest	AppImage (.AppImage)

Artifacts are attached to the GitHub Release automatically.

License

MIT — see LICENSE.