# kunaaaalcodes/nextpr architecture

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

- Interactive diagram: https://gitdiagram.com/kunaaaalcodes/nextpr
- Repository: https://github.com/kunaaaalcodes/nextpr

## Overview

NextPR discovers open GitHub issues, enriches them with repository activity, and ranks them against a developer profile for browsing and recommendations. The graph includes OAuth/profile management, saved issues, and the principal crawl-to-ranked-feed workflow. Several frontend-to-API connections are not shown in the sampled source, so those links are marked unverified rather than asserted.

Main entry points: [`apps/api/src/routes/me.ts`](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/routes/me.ts) (Profile and saved routes), [`apps/api/src/routes/issues.ts`](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/routes/issues.ts) (Issue routes), [`apps/api/src/services/crawler.ts`](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/services/crawler.ts) (Issue crawler), [`apps/api/src/routes/auth.ts`](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/routes/auth.ts) (GitHub OAuth routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webpages["Browse and dashboard"]
  node_savedpage["Saved issues page<br/>[page.tsx]"]
  node_authcallback["Auth callback page<br/>[page.tsx]"]
  node_apiclient["Web API client<br/>[api.ts]"]
  node_webauth["Web auth state<br/>[auth.tsx]"]
end

subgraph group_identity["Identity and profiles"]
  node_oauth["GitHub OAuth routes<br/>[auth.ts]"]
  node_profile["Profile analysis<br/>[profile.ts]"]
  node_user["User model<br/>[User.ts]"]
  node_authmw["API authentication<br/>[auth.ts]"]
  node_me["Profile and saved routes<br/>[me.ts]"]
end

subgraph group_discovery["Issue discovery"]
  node_crawler["Issue crawler<br/>[crawler.ts]"]
  node_scoring["Ranking engine<br/>[scoring.ts]"]
  node_issues["Issue routes<br/>[issues.ts]"]
end

subgraph group_data["Persistence"]
  node_issue["Issue model<br/>[Issue.ts]"]
  node_repo["Repository model<br/>[Repo.ts]"]
  node_database[("MongoDB connection<br/>[db.ts]")]
  node_config["API configuration<br/>[config.ts]"]
  node_server["API server<br/>[index.ts]"]
end

node_developer(("Developer"))
node_github["GitHub API<br/>[github.ts]"]
node_mongo[("MongoDB")]

node_developer -->|"browses recommendations"| node_webpages
node_developer -->|"revisits saved issues"| node_savedpage
node_developer -->|"signs in"| node_authcallback
node_webpages -.->|"requests data"| node_apiclient
node_savedpage -.->|"loads saved issues"| node_apiclient
node_authcallback -.->|"stores session"| node_webauth
node_webauth -->|"uses"| node_apiclient
node_apiclient -.->|"calls API"| node_issues
node_apiclient -.->|"calls API"| node_me
node_oauth -->|"exchanges code"| node_github
node_oauth -->|"fetches account"| node_github
node_oauth -->|"analyzes profile"| node_profile
node_oauth -->|"saves account"| node_user
node_me -->|"requires authentication"| node_authmw
node_me -->|"reads and updates"| node_user
node_me -->|"refreshes profile"| node_github
node_me -->|"reanalyzes profile"| node_profile
node_me -->|"loads saved issues"| node_issue
node_me -->|"loads repository details"| node_repo
node_issues -->|"guards matches"| node_authmw
node_issues -->|"queries issues"| node_issue
node_issues -->|"loads repository data"| node_repo
node_issues -->|"loads profile"| node_user
node_issues -->|"ranks candidates"| node_scoring
node_issues -->|"starts crawl"| node_crawler
node_crawler -->|"fetches issues and repos"| node_github
node_crawler -->|"upserts repository data"| node_repo
node_crawler -->|"upserts issues"| node_issue
node_crawler -->|"infers difficulty"| node_scoring
node_server -->|"connects database"| node_database
node_server -->|"mounts routes"| node_oauth
node_server -->|"mounts routes"| node_issues
node_server -->|"mounts routes"| node_me
node_database -->|"reads settings"| node_config
node_issue -->|"persists documents"| node_mongo
node_repo -->|"persists documents"| node_mongo
node_user -->|"persists documents"| node_mongo

click node_webpages "https://github.com/kunaaaalcodes/nextpr/tree/main/apps/web/src/app"
click node_savedpage "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/web/src/app/saved/page.tsx"
click node_authcallback "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/web/src/app/auth/callback/page.tsx"
click node_apiclient "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/web/src/lib/api.ts"
click node_webauth "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/web/src/lib/auth.tsx"
click node_oauth "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/routes/auth.ts"
click node_github "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/services/github.ts"
click node_profile "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/services/profile.ts"
click node_user "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/models/User.ts"
click node_authmw "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/middleware/auth.ts"
click node_me "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/routes/me.ts"
click node_crawler "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/services/crawler.ts"
click node_scoring "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/services/scoring.ts"
click node_issues "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/routes/issues.ts"
click node_issue "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/models/Issue.ts"
click node_repo "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/models/Repo.ts"
click node_database "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/db.ts"
click node_config "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/config.ts"
click node_server "https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/index.ts"

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_webpages,node_savedpage,node_authcallback,node_apiclient,node_webauth toneBlue
class node_oauth,node_profile,node_user,node_authmw,node_me,node_mongo toneAmber
class node_crawler,node_scoring,node_issues,node_github toneMint
class node_issue,node_repo,node_database,node_config,node_server toneRose
class node_developer toneIndigo
```

## Components

### Web application

- [Browse and dashboard](https://github.com/kunaaaalcodes/nextpr/tree/main/apps/web/src/app): `apps/web/src/app`
- [Saved issues page](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/web/src/app/saved/page.tsx): `apps/web/src/app/saved/page.tsx`
- [Auth callback page](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/web/src/app/auth/callback/page.tsx): `apps/web/src/app/auth/callback/page.tsx`
- [Web API client](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`
- [Web auth state](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/web/src/lib/auth.tsx): `apps/web/src/lib/auth.tsx`

### Identity and profiles

- [GitHub OAuth routes](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/routes/auth.ts): `apps/api/src/routes/auth.ts`
- [Profile analysis](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/services/profile.ts): `apps/api/src/services/profile.ts`
- [User model](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/models/User.ts): `apps/api/src/models/User.ts`
- [API authentication](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/middleware/auth.ts): `apps/api/src/middleware/auth.ts`
- [Profile and saved routes](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/routes/me.ts): `apps/api/src/routes/me.ts`

### Issue discovery

- [Issue crawler](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/services/crawler.ts): `apps/api/src/services/crawler.ts`
- [Ranking engine](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/services/scoring.ts): `apps/api/src/services/scoring.ts`
- [Issue routes](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/routes/issues.ts): `apps/api/src/routes/issues.ts`

### Persistence

- [Issue model](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/models/Issue.ts): `apps/api/src/models/Issue.ts`
- [Repository model](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/models/Repo.ts): `apps/api/src/models/Repo.ts`
- [MongoDB connection](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/db.ts): `apps/api/src/db.ts`
- [API configuration](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/config.ts): `apps/api/src/config.ts`
- [API server](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/index.ts): `apps/api/src/index.ts`

### Other components

- **Developer**
- [GitHub API](https://github.com/kunaaaalcodes/nextpr/blob/main/apps/api/src/services/github.ts): `apps/api/src/services/github.ts`
- **MongoDB**

## Connections

- Developer → Browse and dashboard: browses recommendations (evidence: `README.md`)
- Developer → Saved issues page: revisits saved issues (evidence: `README.md`)
- Developer → Auth callback page: signs in (evidence: `README.md`)
- Browse and dashboard → Web API client: requests data
- Saved issues page → Web API client: loads saved issues
- Auth callback page → Web auth state: stores session
- Web auth state → Web API client: uses (evidence: `apps/web/src/lib/auth.tsx`)
- Web API client → Issue routes: calls API
- Web API client → Profile and saved routes: calls API
- GitHub OAuth routes → GitHub API: exchanges code (evidence: `apps/api/src/routes/auth.ts`)
- GitHub OAuth routes → GitHub API: fetches account (evidence: `apps/api/src/routes/auth.ts`)
- GitHub OAuth routes → Profile analysis: analyzes profile (evidence: `apps/api/src/routes/auth.ts`)
- GitHub OAuth routes → User model: saves account (evidence: `apps/api/src/routes/auth.ts`)
- Profile and saved routes → API authentication: requires authentication (evidence: `apps/api/src/routes/me.ts`)
- Profile and saved routes → User model: reads and updates (evidence: `apps/api/src/routes/me.ts`)
- Profile and saved routes → GitHub API: refreshes profile (evidence: `apps/api/src/routes/me.ts`)
- Profile and saved routes → Profile analysis: reanalyzes profile (evidence: `apps/api/src/routes/me.ts`)
- Profile and saved routes → Issue model: loads saved issues (evidence: `apps/api/src/routes/me.ts`)
- Profile and saved routes → Repository model: loads repository details (evidence: `apps/api/src/routes/me.ts`)
- Issue routes → API authentication: guards matches (evidence: `apps/api/src/routes/issues.ts`)
- Issue routes → Issue model: queries issues (evidence: `apps/api/src/routes/issues.ts`)
- Issue routes → Repository model: loads repository data (evidence: `apps/api/src/routes/issues.ts`)
- Issue routes → User model: loads profile (evidence: `apps/api/src/routes/issues.ts`)
- Issue routes → Ranking engine: ranks candidates (evidence: `apps/api/src/routes/issues.ts`)
- Issue routes → Issue crawler: starts crawl (evidence: `apps/api/src/routes/issues.ts`)
- Issue crawler → GitHub API: fetches issues and repos (evidence: `apps/api/src/services/crawler.ts`)
- Issue crawler → Repository model: upserts repository data (evidence: `apps/api/src/services/crawler.ts`)
- Issue crawler → Issue model: upserts issues (evidence: `apps/api/src/services/crawler.ts`)
- Issue crawler → Ranking engine: infers difficulty (evidence: `apps/api/src/services/crawler.ts`)
- API server → MongoDB connection: connects database (evidence: `apps/api/src/index.ts`)
- API server → GitHub OAuth routes: mounts routes (evidence: `apps/api/src/index.ts`)
- API server → Issue routes: mounts routes (evidence: `apps/api/src/index.ts`)
- API server → Profile and saved routes: mounts routes (evidence: `apps/api/src/index.ts`)
- MongoDB connection → API configuration: reads settings (evidence: `apps/api/src/db.ts`)
- Issue model → MongoDB: persists documents (evidence: `apps/api/src/models/Issue.ts`)
- Repository model → MongoDB: persists documents (evidence: `apps/api/src/models/Repo.ts`)
- User model → MongoDB: persists documents (evidence: `apps/api/src/models/User.ts`)
