OSS Passport

OSS Passport is a Django MVP that turns a developer's public GitHub profile into a shareable passport artifact.

Architecture

App boundaries

• config/: Django project settings and root URLs.
• apps/core/: landing page and static marketing views.
• apps/github_integration/: GitHub API client and profile aggregation services.
• apps/passports/: domain models, generation services, forms, public passport pages, and share assets.
• apps/users/: GitHub-authenticated account flow built on Django's User model plus a profile extension.

Domain model

• GitHubProfileSource: cached public GitHub identity and raw payload.
• Passport: generated artifact linked one-to-one with a source profile and optionally owned by a Django user.
• RepositorySummary: selected repositories shown on a passport.
• Stamp: inferred contribution badges with transparent evidence.
• ShareAsset: generated README, embed, and social-preview payloads.
• UserProfile: GitHub identity fields attached to Django's built-in User.

Service layer

• GitHubClient: thin HTTP wrapper around the public GitHub REST API.
• GitHubProfileService: fetches and normalizes profile, repositories, languages, and featured repos.
• PassportGeneratorService: orchestrates import, persistence, and artifact generation.
• StampInferenceService: applies explicit inference rules to produce stamps.
• ShareAssetService: builds README, embed, and social preview outputs.

URL map

• /: landing page
• /generate/: username-based generation flow
• /login/: branded GitHub sign-in handoff
• /p/<public_slug>/: passport detail page, private by default

Local setup

1. Create a virtual environment.
2. Install dependencies with pip install -r requirements.txt.
3. Copy .env.example to .env if you want custom settings.
4. Run python manage.py migrate.
5. Run python manage.py seed_oss_passport_demo for demo data.
6. Start the server with python manage.py runserver.

GitHub OAuth setup

Add these environment variables before using the sign-in flow:

• GITHUB_OAUTH_CLIENT_ID
• GITHUB_OAUTH_SECRET

The GitHub OAuth app should request read:user, user:email, and read:org so authenticated imports can include organization memberships and richer contribution summaries.

Notes

• SQLite is the default database for fast local iteration.
• The settings are already structured so PostgreSQL can replace SQLite later with minimal changes.
• Public GitHub import works without OAuth; a GITHUB_TOKEN simply increases API headroom.
• Passports are private by default. Anonymous users can prepare one, then claim and view it by signing in with the matching GitHub account.