# coder-s-og-s/mergeship architecture

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

- Interactive diagram: https://gitdiagram.com/coder-s-og-s/mergeship
- Repository: https://github.com/coder-s-og-s/mergeship

## Overview

MergeShip serves contributors learning and finding appropriately leveled open-source work, and maintainers reviewing organization activity and PRs. The main contributor path runs from profile analysis and placement through learning/mentorship, recommended issues, PR activity, and XP; maintainers use dashboards, PR review, analytics, and contributor-management tools. GitHub events enter through a verified webhook and are dispatched to background functions. Edges are limited to README-documented behavior or relationships visible in supplied excerpts and the source index; dashed edges mark workflow links not directly evidenced in sampled source.

Main entry points: [`src/app/(app)/maintainer/page.tsx`](https://github.com/coder-s-og-s/mergeship/blob/main/src/app/(app)/maintainer/page.tsx) (Organization dashboard), [`src/inngest/functions/process-pr-event.ts`](https://github.com/coder-s-og-s/mergeship/blob/main/src/inngest/functions/process-pr-event.ts) (PR event processing), [`src/app/actions/profile.ts`](https://github.com/coder-s-og-s/mergeship/blob/main/src/app/actions/profile.ts) (Profile analysis), [`src/inngest/functions/recommendations-worker.ts`](https://github.com/coder-s-og-s/mergeship/blob/main/src/inngest/functions/recommendations-worker.ts) (Issue recommendations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contributor["Contributor experience"]
  node_onboarding["Placement onboarding<br/>[page.tsx]"]
  node_profile["Profile analysis<br/>[profile.ts]"]
  node_course["Foundational course"]
  node_recommendations["Issue recommendations"]
  node_mentor["Peer mentorship<br/>[mentor.ts]"]
  node_challenge["Daily challenges<br/>[progress.ts]"]
  node_contributor_ui["Contributor dashboard"]
end

subgraph group_maintainer["Maintainer workspace"]
  node_maintainer_ui["Organization dashboard<br/>[page.tsx]"]
  node_pr_review["PR review workflow<br/>[page.tsx]"]
  node_analytics["Maintainer analytics<br/>[page.tsx]"]
  node_contributors_admin["Contributor management<br/>[page.tsx]"]
  node_community["Community communication<br/>[page.tsx]"]
end

subgraph group_background["Integrations and jobs"]
  node_github(("GitHub"))
  node_webhook["GitHub webhook intake<br/>[route.ts]"]
  node_inngest_route["Background job dispatch<br/>[route.ts]"]
  node_pr_event["PR event processing"]
  node_review_event["Review event processing"]
end

subgraph group_platform["Core services and data"]
  node_ranking["Issue ranking<br/>[recommend.ts]"]
  node_xp["XP and levels<br/>[events.ts]"]
  node_github_api["GitHub API client<br/>[app.ts]"]
  node_llm["LLM routing<br/>[router.ts]"]
  node_supabase[("Supabase")]
  node_db["Typed database access<br/>[client.ts]"]
  node_schema[("Application data schema<br/>[schema.ts]")]
  node_cache[("Cache and rate limits<br/>[cache.ts]")]
end

node_contributors(("Contributors"))
node_maintainers(("Maintainers"))

node_contributors -->|"sign in"| node_onboarding
node_onboarding -.->|"analyzes profile"| node_profile
node_github -.->|"profile data"| node_profile
node_profile -.->|"places contributor"| node_course
node_contributors -->|"learn and contribute"| node_contributor_ui
node_contributor_ui -.->|"view recommendations"| node_recommendations
node_recommendations -->|"ranks issues"| node_ranking
node_recommendations -->|"reads and writes"| node_supabase
node_contributors -->|"seek mentorship"| node_mentor
node_mentor -.->|"peer review"| node_contributors
node_contributors -->|"earn points"| node_xp
node_contributors -.->|"track progress"| node_challenge
node_maintainers -->|"manage organization"| node_maintainer_ui
node_maintainer_ui -.->|"review pull requests"| node_pr_review
node_maintainer_ui -.->|"inspect activity"| node_analytics
node_maintainer_ui -.->|"manage contributors"| node_contributors_admin
node_maintainer_ui -->|"communicate directly"| node_community
node_github -->|"sends events"| node_webhook
node_webhook -->|"dispatches events"| node_inngest_route
node_inngest_route -->|"registers handler"| node_pr_event
node_inngest_route -->|"registers handler"| node_review_event
node_pr_event -->|"updates PR data"| node_supabase
node_review_event -->|"reads and writes"| node_supabase
node_review_event -->|"records review XP"| node_xp
node_pr_event -->|"records contribution XP"| node_xp
node_pr_event -.->|"uses GitHub integration"| node_github_api
node_github_api -->|"caches tokens"| node_cache
node_github_api -->|"calls API"| node_github
node_llm -.->|"supports triage"| node_supabase
node_db -->|"configures queries"| node_schema
node_profile -->|"uses server client"| node_supabase

click node_onboarding "https://github.com/coder-s-og-s/mergeship/blob/main/src/app/onboarding/analyze/page.tsx"
click node_profile "https://github.com/coder-s-og-s/mergeship/blob/main/src/app/actions/profile.ts"
click node_course "https://github.com/coder-s-og-s/mergeship/blob/main/src/components/contributor-dashboard/course-progress.tsx"
click node_recommendations "https://github.com/coder-s-og-s/mergeship/blob/main/src/inngest/functions/recommendations-worker.ts"
click node_ranking "https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/pipeline/recommend.ts"
click node_mentor "https://github.com/coder-s-og-s/mergeship/blob/main/src/app/actions/mentor.ts"
click node_xp "https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/xp/events.ts"
click node_challenge "https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/daily-challenge/progress.ts"
click node_contributor_ui "https://github.com/coder-s-og-s/mergeship/blob/main/src/components/contributor-dashboard/profile-sidebar.tsx"
click node_maintainer_ui "https://github.com/coder-s-og-s/mergeship/blob/main/src/app/(app)/maintainer/page.tsx"
click node_pr_review "https://github.com/coder-s-og-s/mergeship/blob/main/src/app/(app)/maintainer/pr/%5Bid%5D/page.tsx"
click node_analytics "https://github.com/coder-s-og-s/mergeship/blob/main/src/app/(app)/maintainer/analytics/page.tsx"
click node_contributors_admin "https://github.com/coder-s-og-s/mergeship/blob/main/src/app/(app)/maintainer/contributors/page.tsx"
click node_community "https://github.com/coder-s-og-s/mergeship/blob/main/src/app/(app)/maintainer/community/page.tsx"
click node_webhook "https://github.com/coder-s-og-s/mergeship/blob/main/src/app/api/webhooks/github/route.ts"
click node_inngest_route "https://github.com/coder-s-og-s/mergeship/blob/main/src/app/api/inngest/route.ts"
click node_pr_event "https://github.com/coder-s-og-s/mergeship/blob/main/src/inngest/functions/process-pr-event.ts"
click node_review_event "https://github.com/coder-s-og-s/mergeship/blob/main/src/inngest/functions/process-review-event.ts"
click node_github_api "https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/github/app.ts"
click node_llm "https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/llm/router.ts"
click node_db "https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/db/client.ts"
click node_schema "https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/db/schema.ts"
click node_cache "https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/cache.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_onboarding,node_profile,node_course,node_recommendations,node_mentor,node_challenge,node_contributor_ui toneBlue
class node_maintainer_ui,node_pr_review,node_analytics,node_contributors_admin,node_community toneAmber
class node_github,node_webhook,node_inngest_route,node_pr_event,node_review_event toneMint
class node_ranking,node_xp,node_github_api,node_llm,node_supabase,node_db,node_schema,node_cache toneRose
class node_contributors,node_maintainers toneIndigo
```

## Components

### Contributor experience

- [Placement onboarding](https://github.com/coder-s-og-s/mergeship/blob/main/src/app/onboarding/analyze/page.tsx): `src/app/onboarding/analyze/page.tsx`
- [Profile analysis](https://github.com/coder-s-og-s/mergeship/blob/main/src/app/actions/profile.ts): `src/app/actions/profile.ts`
- [Foundational course](https://github.com/coder-s-og-s/mergeship/blob/main/src/components/contributor-dashboard/course-progress.tsx): `src/components/contributor-dashboard/course-progress.tsx`
- [Issue recommendations](https://github.com/coder-s-og-s/mergeship/blob/main/src/inngest/functions/recommendations-worker.ts): `src/inngest/functions/recommendations-worker.ts`
- [Peer mentorship](https://github.com/coder-s-og-s/mergeship/blob/main/src/app/actions/mentor.ts): `src/app/actions/mentor.ts`
- [Daily challenges](https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/daily-challenge/progress.ts): `src/lib/daily-challenge/progress.ts`
- [Contributor dashboard](https://github.com/coder-s-og-s/mergeship/blob/main/src/components/contributor-dashboard/profile-sidebar.tsx): `src/components/contributor-dashboard/profile-sidebar.tsx`

### Maintainer workspace

- [Organization dashboard](https://github.com/coder-s-og-s/mergeship/blob/main/src/app/(app)/maintainer/page.tsx): `src/app/(app)/maintainer/page.tsx`
- [PR review workflow](https://github.com/coder-s-og-s/mergeship/blob/main/src/app/(app)/maintainer/pr/%5Bid%5D/page.tsx): `src/app/(app)/maintainer/pr/[id]/page.tsx`
- [Maintainer analytics](https://github.com/coder-s-og-s/mergeship/blob/main/src/app/(app)/maintainer/analytics/page.tsx): `src/app/(app)/maintainer/analytics/page.tsx`
- [Contributor management](https://github.com/coder-s-og-s/mergeship/blob/main/src/app/(app)/maintainer/contributors/page.tsx): `src/app/(app)/maintainer/contributors/page.tsx`
- [Community communication](https://github.com/coder-s-og-s/mergeship/blob/main/src/app/(app)/maintainer/community/page.tsx): `src/app/(app)/maintainer/community/page.tsx`

### Integrations and jobs

- **GitHub**
- [GitHub webhook intake](https://github.com/coder-s-og-s/mergeship/blob/main/src/app/api/webhooks/github/route.ts): `src/app/api/webhooks/github/route.ts`
- [Background job dispatch](https://github.com/coder-s-og-s/mergeship/blob/main/src/app/api/inngest/route.ts): `src/app/api/inngest/route.ts`
- [PR event processing](https://github.com/coder-s-og-s/mergeship/blob/main/src/inngest/functions/process-pr-event.ts): `src/inngest/functions/process-pr-event.ts`
- [Review event processing](https://github.com/coder-s-og-s/mergeship/blob/main/src/inngest/functions/process-review-event.ts): `src/inngest/functions/process-review-event.ts`

### Core services and data

- [Issue ranking](https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/pipeline/recommend.ts): `src/lib/pipeline/recommend.ts`
- [XP and levels](https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/xp/events.ts): `src/lib/xp/events.ts`
- [GitHub API client](https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/github/app.ts): `src/lib/github/app.ts`
- [LLM routing](https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/llm/router.ts): `src/lib/llm/router.ts`
- **Supabase**
- [Typed database access](https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/db/client.ts): `src/lib/db/client.ts`
- [Application data schema](https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/db/schema.ts): `src/lib/db/schema.ts`
- [Cache and rate limits](https://github.com/coder-s-og-s/mergeship/blob/main/src/lib/cache.ts): `src/lib/cache.ts`

### Other components

- **Contributors**
- **Maintainers**

## Connections

- Contributors → Placement onboarding: sign in
- Placement onboarding → Profile analysis: analyzes profile
- GitHub → Profile analysis: profile data
- Profile analysis → Foundational course: places contributor
- Contributors → Contributor dashboard: learn and contribute
- Contributor dashboard → Issue recommendations: view recommendations
- Issue recommendations → Issue ranking: ranks issues (evidence: `src/inngest/functions/recommendations-worker.ts`)
- Issue recommendations → Supabase: reads and writes (evidence: `src/inngest/functions/recommendations-worker.ts`)
- Contributors → Peer mentorship: seek mentorship
- Peer mentorship → Contributors: peer review
- Contributors → XP and levels: earn points
- Contributors → Daily challenges: track progress
- Maintainers → Organization dashboard: manage organization
- Organization dashboard → PR review workflow: review pull requests
- Organization dashboard → Maintainer analytics: inspect activity
- Organization dashboard → Contributor management: manage contributors
- Organization dashboard → Community communication: communicate directly
- GitHub → GitHub webhook intake: sends events
- GitHub webhook intake → Background job dispatch: dispatches events (evidence: `src/app/api/webhooks/github/route.ts`)
- Background job dispatch → PR event processing: registers handler (evidence: `src/app/api/inngest/route.ts`)
- Background job dispatch → Review event processing: registers handler (evidence: `src/app/api/inngest/route.ts`)
- PR event processing → Supabase: updates PR data (evidence: `src/inngest/functions/process-pr-event.ts`)
- Review event processing → Supabase: reads and writes (evidence: `src/inngest/functions/process-review-event.ts`)
- Review event processing → XP and levels: records review XP (evidence: `src/inngest/functions/process-review-event.ts`)
- PR event processing → XP and levels: records contribution XP (evidence: `src/inngest/functions/process-pr-event.ts`)
- PR event processing → GitHub API client: uses GitHub integration
- GitHub API client → Cache and rate limits: caches tokens (evidence: `src/lib/github/app.ts`)
- GitHub API client → GitHub: calls API (evidence: `src/lib/github/app.ts`)
- LLM routing → Supabase: supports triage
- Typed database access → Application data schema: configures queries (evidence: `src/lib/db/client.ts`)
- Profile analysis → Supabase: uses server client (evidence: `src/app/actions/profile.ts`)