OpenPath

AI-powered open-source contribution recommendation platform. OpenPath helps student and early-career developers find their first (or next) open-source contribution by matching their skills and interests to real repositories and beginner-friendly issues, then guiding them through the contribution with an AI mentor, a learning-gap analyzer, a contribution tracker, and an auto-generated resume.

---

Features

• Personalized recommendations — repositories and "good first issues" ranked by a weighted match score (tech stack, interests, difficulty, activity, docs).
• AI Mentor — chat-based guidance that explains repositories and issues in beginner-friendly language and produces step-by-step contribution roadmaps.
• Readiness & learning gaps — analyzes the skills a repo needs versus the ones you have and proposes a prioritized learning path with free resources.
• Contribution tracker — track issues and PRs you're working on across repos.
• Resume builder — turns your merged contributions into resume-ready summaries.
• GitHub integration — OAuth login plus profile analysis from your GitHub activity.

The AI features run against any OpenAI-compatible provider (OpenAI, Groq, Gemini, OpenRouter, Ollama, …). When no real API key is configured in development, the backend transparently serves mock AI responses so the whole app is usable offline.

---

Tech stack

Layer	Technology
Frontend	Next.js 15 (App Router) · React 19 · TypeScript · Tailwind · Radix UI · TanStack Query · Framer Motion
Backend	FastAPI · SQLAlchemy 2 (async) · Pydantic v2 · Alembic
Data	PostgreSQL 16 · Redis 7 (cache + Celery broker)
Async	Celery (background workers + beat) · Flower (monitoring)
AI	OpenAI-compatible Chat Completions API
Infra	Docker Compose · GitHub Actions CI

---

Project layout

openpath/
├── backend/                # FastAPI application
│   ├── app/
│   │   ├── api/v1/          # Route handlers (auth, profile, recommendations, mentor, …)
│   │   ├── core/           # Config, database, security, redis, logging, exceptions
│   │   ├── models/         # SQLAlchemy models
│   │   ├── schemas/        # Pydantic request/response models
│   │   ├── repositories/   # Data-access layer
│   │   ├── services/       # Business logic (AI, recommendations, github, …)
│   │   ├── workers/        # Celery app + tasks
│   │   └── main.py         # App entrypoint
│   ├── alembic/            # Database migrations
│   ├── scripts/seed.py     # Demo data seeder
│   └── tests/              # Pytest suite
├── frontend/               # Next.js application (src/app/* pages)
├── docker-compose.yml      # Full local stack
└── .github/workflows/ci.yml

---

Getting started

Prerequisites

• Docker + Docker Compose — or — Python 3.12+, Node.js 20+, PostgreSQL 16, Redis 7
• A GitHub OAuth app (Client ID + Secret) for login
• (Optional) an API key for an OpenAI-compatible AI provider

1. Configure environment

cp .env.example .env

Edit .env and set, at minimum:

Variable	Notes
SECRET_KEY, JWT_SECRET_KEY	Any random 32+ character strings
DATABASE_URL	e.g. postgresql+asyncpg://openpath:openpath@localhost:5432/openpath
REDIS_URL, CELERY_BROKER_URL, CELERY_RESULT_BACKEND	e.g. redis://localhost:6379/0
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET	From your GitHub OAuth app
OPENAI_API_KEY	A real key, or leave it as a placeholder to use mock AI in dev
OPENAI_BASE_URL, OPENAI_MODEL	Point these at your provider (see AI providers)

2. Run with Docker (recommended)

docker compose up --build

This starts Postgres, Redis, the backend, Celery worker + beat, Flower, and the frontend. Once up:

• Frontend → http://localhost:3000
• API docs (Swagger) → http://localhost:8000/docs
• Flower (Celery) → http://localhost:5555

3. Run manually (without Docker)

Backend

cd backend
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
alembic upgrade head          # apply migrations
python scripts/seed.py        # (optional) load demo data
uvicorn app.main:app --reload --port 8000

Frontend

cd frontend
npm install
npm run dev                   # http://localhost:3000

Note: uvicorn --reload does not re-read .env. After editing env values, touch any .py file (or restart) to pick up the change.

---

AI providers

The backend talks to any OpenAI-compatible Chat Completions endpoint. Configure the provider entirely through env vars:

# OpenAI (default)
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

# Gemini (OpenAI-compatible endpoint)
OPENAI_API_KEY=...
OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
OPENAI_MODEL=gemini-2.0-flash

# Groq
OPENAI_API_KEY=gsk_...
OPENAI_BASE_URL=https://api.groq.com/openai/v1
OPENAI_MODEL=llama-3.3-70b-versatile

Mock mode: in development, if OPENAI_API_KEY is empty or a known placeholder (sk-test-key, changeme, sk-your-..., …), the app serves canned AI responses instead of making network calls — so you can develop the full UI without billing. With a real key configured, errors are surfaced rather than silently masked as "demo mode".

---

Testing

The backend test suite is fast and service-independent (pure logic + ASGI route smoke tests with no lifespan), so it runs with no Postgres/Redis required:

cd backend
pytest                                   # or: pytest --cov=app --cov-report=term-missing

tests/conftest.py sets safe default env vars before importing the app, so the suite works locally and in CI alike.

---

Continuous integration

.github/workflows/ci.yml runs on pushes/PRs to main and develop:

• Frontend — npm run type-check, lint, and build
• Backend — flake8, mypy (non-blocking), and pytest with coverage, against ephemeral Postgres and Redis service containers
• Docker — builds production images for both apps (on main only)

---

License

See repository for license details.