# vinaykumarbharwal/gitniche architecture

> Architecture diagram of the GitHub repository vinaykumarbharwal/gitniche, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vinaykumarbharwal/gitniche
- Repository: https://github.com/vinaykumarbharwal/gitniche

## Overview

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: [`backend/app/main.py`](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/main.py) (Backend API), [`backend/app/routes/search.py`](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/routes/search.py) (Search Route), [`backend/app/services/github_service.py`](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/services/github_service.py) (GitHub Service), [`backend/app/services/supabase_service.py`](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/services/supabase_service.py) (Supabase DB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Frontend App<br/>next app"]
  node_frontend_routes["App Routes<br/>route pages"]
  node_ui_components["UI Components<br/>ui kit"]
  node_api_client["API Client<br/>service client<br/>[api.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_api["Backend API<br/>fastapi app<br/>[main.py]"]
  node_search_route["Search Route<br/>discovery endpoint<br/>[search.py]"]
  node_user_routes["User Routes<br/>state endpoints<br/>[preferences.py]"]
  node_auth_route["Auth Route<br/>oauth endpoint<br/>[auth.py]"]
  node_github_service["GitHub Service<br/>github integration<br/>[github_service.py]"]
  node_hf_scoring["ML Scoring<br/>enrichment service"]
  node_scoring_service["Score Engine<br/>ranking service<br/>[scoring_service.py]"]
end

subgraph group_data["Data & Ops"]
  node_schema_seed["Schema & Seed<br/>db bootstrap<br/>[schema.sql]"]
  node_repo_ops["Repo Ops<br/>offline scripts<br/>[find_repos.py]"]
  node_found_dataset["Found Dataset<br/>curated json<br/>[found_repos.json]"]
end

subgraph group_external["External"]
  node_redis_cache[("Redis Cache<br/>cache layer<br/>[redis_service.py]")]
  node_supabase_db[("Supabase DB<br/>postgres store")]
  node_github_api(("GitHub API<br/>external api"))
  node_huggingface_api(("Hugging Face<br/>external api"))
end

node_browser(("Browser<br/>user client"))

node_browser -->|"use app"| node_frontend_app
node_frontend_app -->|"renders"| node_frontend_routes
node_frontend_routes -->|"composes"| node_ui_components
node_ui_components -->|"query data"| node_api_client
node_api_client -->|"call api"| node_backend_api
node_backend_api -->|"search"| node_search_route
node_backend_api -->|"user state"| node_user_routes
node_backend_api -->|"login"| node_auth_route
node_search_route -->|"fetch data"| node_github_service
node_search_route -->|"classify"| node_hf_scoring
node_search_route -->|"rank"| node_scoring_service
node_github_service -->|"cache"| node_redis_cache
node_github_service -->|"source"| node_github_api
node_hf_scoring -->|"model call"| node_huggingface_api
node_user_routes -->|"persist"| node_supabase_db
node_auth_route -->|"bootstrap user"| node_supabase_db
node_supabase_db -->|"defined by"| node_schema_seed
node_repo_ops -->|"curate"| node_found_dataset
node_repo_ops -.->|"seed"| node_schema_seed

click node_frontend_app "https://github.com/vinaykumarbharwal/gitniche/tree/main/frontend/src/app"
click node_frontend_routes "https://github.com/vinaykumarbharwal/gitniche/tree/main/frontend/src/app"
click node_ui_components "https://github.com/vinaykumarbharwal/gitniche/tree/main/frontend/src/components"
click node_api_client "https://github.com/vinaykumarbharwal/gitniche/blob/main/frontend/src/services/api.ts"
click node_backend_api "https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/main.py"
click node_search_route "https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/routes/search.py"
click node_user_routes "https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/routes/preferences.py"
click node_auth_route "https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/routes/auth.py"
click node_github_service "https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/services/github_service.py"
click node_hf_scoring "https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/services/huggingface_service.py"
click node_scoring_service "https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/services/scoring_service.py"
click node_redis_cache "https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/services/redis_service.py"
click node_supabase_db "https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/services/supabase_service.py"
click node_schema_seed "https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/schema.sql"
click node_repo_ops "https://github.com/vinaykumarbharwal/gitniche/blob/main/find_repos.py"
click node_found_dataset "https://github.com/vinaykumarbharwal/gitniche/blob/main/found_repos.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_routes,node_ui_components,node_api_client toneBlue
class node_backend_api,node_search_route,node_user_routes,node_auth_route,node_github_service,node_hf_scoring,node_scoring_service toneAmber
class node_schema_seed,node_repo_ops,node_found_dataset toneMint
class node_redis_cache,node_supabase_db,node_github_api,node_huggingface_api toneRose
class node_browser toneNeutral
```

## Components

### Frontend

Next.js App Router discovery UI and client-side interaction layer.

- [Frontend App](https://github.com/vinaykumarbharwal/gitniche/tree/main/frontend/src/app): next app · Next.js App Router application and page shell. · `frontend/src/app`
- [App Routes](https://github.com/vinaykumarbharwal/gitniche/tree/main/frontend/src/app): route pages · Home, saved, profile, auth callback, and informational pages. · `frontend/src/app`
- [UI Components](https://github.com/vinaykumarbharwal/gitniche/tree/main/frontend/src/components): ui kit · Reusable controls for search, filters, cards, navbar, and preferences. · `frontend/src/components`
- [API Client](https://github.com/vinaykumarbharwal/gitniche/blob/main/frontend/src/services/api.ts): service client · Centralized frontend calls into the backend API. · `frontend/src/services/api.ts`

### Backend

FastAPI API, domain routes, and enrichment services.

- [Backend API](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/main.py): fastapi app · Thin HTTP layer that composes search, auth, and user-state operations. · `backend/app/main.py`
- [Search Route](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/routes/search.py): discovery endpoint · Repository search and filtering endpoint returning scored results. · `backend/app/routes/search.py`
- [User Routes](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/routes/preferences.py): state endpoints · Preferences and saved-repository endpoints for authenticated user state. · `backend/app/routes/preferences.py`
- [Auth Route](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/routes/auth.py): oauth endpoint · GitHub-based login, callback handling, and session bootstrap. · `backend/app/routes/auth.py`
- [GitHub Service](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/services/github_service.py): github integration · Fetches repository metadata, issues, and other raw GitHub data. · `backend/app/services/github_service.py`
- [ML Scoring](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/services/huggingface_service.py): enrichment service · Labels domains and computes GitNiche scores from repository signals. · `backend/app/services/huggingface_service.py`
- [Score Engine](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/services/scoring_service.py): ranking service · 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](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/schema.sql): db bootstrap · Database schema and reproducible seed path for local or initial deployment. · `backend/schema.sql`
- [Repo Ops](https://github.com/vinaykumarbharwal/gitniche/blob/main/find_repos.py): offline scripts · Repository collection and opportunity-generation scripts outside the live path. · `find_repos.py`
- [Found Dataset](https://github.com/vinaykumarbharwal/gitniche/blob/main/found_repos.json): curated json · Auxiliary repository corpus used by offline tooling and curation. · `found_repos.json`

### External

Third-party APIs and managed infrastructure boundaries.

- [Redis Cache](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/services/redis_service.py): cache layer · Caches repeated GitHub lookups and buffers API rate limits. · `backend/app/services/redis_service.py`
- [Supabase DB](https://github.com/vinaykumarbharwal/gitniche/blob/main/backend/app/services/supabase_service.py): postgres store · Persistent store for users, preferences, bookmarks, and search history. · `backend/app/services/supabase_service.py`
- **GitHub API**: external api · Source of truth for live repository and issue metadata.
- **Hugging Face**: external api · Model and labeling boundary used for repository classification.

### Other components

- **Browser**: user client · User-facing discovery experience in the browser.

## Connections

- 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.
