How vinaykumarbharwal/gitniche works
1. GitNiche is split into two independently deployed runtimes: a FastAPI backend in backend/ and a Next.js App Router frontend in frontend/. The backend owns data access, enrichment, auth, and scoring; the frontend owns rendering, filtering UI, and user interaction.
2. The frontend is the user-facing discovery app. Its main routes are the home search page, saved repositories, profile/preferences, and informational pages like about, contact, privacy, and terms. The auth/callback page is part of the sign-in flow.
3. The frontend is organized around reusable UI controls rather than heavy client state: SearchBar, Filters, RepoCard, RepoCardSkeleton, Navbar, and PreferencesForm. These components feed into a small API layer in src/services/api.ts, which centralizes calls to the backend.
4. The core user flow is search and filtering. A user enters a query or selects domains/difficulty/language filters in the frontend, which calls the backend search route. The backend returns scored repositories, and the UI renders them as cards with metadata like stars, issues, last update, and “good first issue” signals.
5. The backend routes are domain-oriented: search.py for repository discovery, preferences.py for saved user settings, saved_repos.py for bookmarks, and auth.py for GitHub-based login/session handling. This keeps the HTTP layer thin and separates user concerns from repository enrichment logic.
6. Repository enrichment is handled by backend services rather than routes. github_service.py fetches raw GitHub repository and issue data, huggingface_service.py likely classifies or labels repository domains/difficulty, and scoring_service.py computes the GitNiche score. The route layer composes these outputs into the API response.
7. redis_service.py provides caching to reduce repeated GitHub calls and mitigate rate limits. The README notes Upstash Redis with local TTL fallbacks, so the architecture includes a cache boundary between search traffic and external GitHub API usage.
8. supabase_service.py is the persistence boundary. The database schema in schema.sql defines users, user preferences, saved repositories, and search history. Supabase/PostgreSQL stores identity-linked state, while GitHub remains the source of truth for repository metadata.
9. The data model is centered on a user account linked to GitHub. Preferences store domains, languages, experience level, and career goal; saved repositories store a normalized bookmark record plus score and classification; search history records queries and filter state for later reuse or personalization.
10. Authentication and profile management are tied to GitHub identity. The backend auth route likely handles OAuth exchange and user bootstrap, while the frontend callback page completes the sign-in experience. Once authenticated, the profile page lets users manage preferences and perform destructive cleanup actions such as clearing bookmarks or deleting account records.
11. There is a clear separation between transient discovery data and durable user data. Search results are generated on demand from GitHub and cache layers, while preferences, bookmarks, and history are persisted in Supabase and cascade with user deletion.
12. The repo also includes offline/auxiliary data workflows: find_repos.py, fetch_opportunities.py, and found_repos.json suggest repository collection or dataset generation outside the live request path. These scripts are not part of the main app runtime but support seeding or curating discovery data.
13. seed_db.py and schema.sql indicate a reproducible database setup path for local or initial deployment. Configuration is environment-driven via backend/app/config.py and .env.example, which matches the decoupled frontend/backend deployment model.
14. From an architecture-diagram perspective, the most important boundaries are: browser UI, FastAPI API, external GitHub/Hugging Face services, Redis cache, and Supabase/Postgres persistence. The primary flows are search/enrichment, auth/bootstrap, preference updates, and bookmark/history writes.
Main entry points: main.py Backend API · search.py Search Route · github_service.py GitHub Service · supabase_service.py Supabase DB
Components 19
Frontend
Next.js App Router discovery UI and client-side interaction layer.
- Frontend App · Next.js App Router application and page shell.
frontend/src/app - App Routes · Home, saved, profile, auth callback, and informational pages.
frontend/src/app - UI Components · Reusable controls for search, filters, cards, navbar, and preferences.
frontend/src/components - API Client · Centralized frontend calls into the backend API.
frontend/src/services/api.ts
Backend
FastAPI API, domain routes, and enrichment services.
- Backend API · Thin HTTP layer that composes search, auth, and user-state operations.
backend/app/main.py - Search Route · Repository search and filtering endpoint returning scored results.
backend/app/routes/search.py - User Routes · Preferences and saved-repository endpoints for authenticated user state.
backend/app/routes/preferences.py - Auth Route · GitHub-based login, callback handling, and session bootstrap.
backend/app/routes/auth.py - GitHub Service · Fetches repository metadata, issues, and other raw GitHub data.
backend/app/services/github_service.py - ML Scoring · Labels domains and computes GitNiche scores from repository signals.
backend/app/services/huggingface_service.py - Score Engine · Combines enrichment outputs into the final repository score.
backend/app/services/scoring_service.py
Data & Ops
Persistence schema and offline repository collection workflows.
- Schema & Seed · Database schema and reproducible seed path for local or initial deployment.
backend/schema.sql - Repo Ops · Repository collection and opportunity-generation scripts outside the live path.
find_repos.py - Found Dataset · Auxiliary repository corpus used by offline tooling and curation.
found_repos.json
External
Third-party APIs and managed infrastructure boundaries.
- Redis Cache · Caches repeated GitHub lookups and buffers API rate limits.
backend/app/services/redis_service.py - Supabase DB · Persistent store for users, preferences, bookmarks, and search history.
backend/app/services/supabase_service.py - GitHub API · Source of truth for live repository and issue metadata.
- Hugging Face · Model and labeling boundary used for repository classification.
Other components
- Browser · User-facing discovery experience in the browser.
Connections 19
- Browser → Frontend App: use app · Users interact with the Next.js frontend in the browser.
- Frontend App → App Routes: renders · The app serves search, saved, profile, auth callback, and info pages.
- App Routes → UI Components: composes · Pages assemble reusable search, filter, card, and form controls.
- UI Components → API Client: query data · Search and preference controls trigger backend requests through the shared API layer.
- API Client → Backend API: call api · Frontend requests are centralized through the backend HTTP surface.
- Backend API → Search Route: search · The search endpoint handles discovery and ranking requests.
- Backend API → User Routes: user state · Preferences and saved repositories are managed as authenticated user state.
- Backend API → Auth Route: login · The auth flow exchanges GitHub identity and bootstraps sessions.
- Search Route → GitHub Service: fetch data · Search composes raw repository and issue data from GitHub.
- Search Route → ML Scoring: classify · Repository signals are enriched with domain and difficulty labels.
- Search Route → Score Engine: rank · Enrichment outputs are turned into the final GitNiche score.
- GitHub Service → Redis Cache: cache · GitHub lookups are cached to reduce repeated calls.
- GitHub Service → GitHub API: source · Live repository metadata is pulled from GitHub.
- ML Scoring → Hugging Face: model call · Classification and labeling depend on Hugging Face-backed inference.
- User Routes → Supabase DB: persist · Preferences, bookmarks, and history are stored in Supabase/Postgres.
- Auth Route → Supabase DB: bootstrap user · OAuth login is tied to persistent user records and session state.
- Supabase DB → Schema & Seed: defined by · Schema and seed scripts define the persistence structure.
- Repo Ops → Found Dataset: curate · Offline scripts generate or curate repository discovery data.
- Repo Ops → Schema & Seed: seed · Auxiliary workflows support database initialization and local setup.