# s3dfx-cyber/gsoc-org-finder- architecture

> Architecture diagram of the GitHub repository s3dfx-cyber/gsoc-org-finder-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/s3dfx-cyber/gsoc-org-finder-
- Repository: https://github.com/s3dfx-cyber/gsoc-org-finder-

## Overview

#### Purpose and Entry Points
GSoC 2026 Org Finder is a static, browser-first directory for discovering and comparing GSoC organizations by tags, domain, competition, activity, and beginner issues. The primary page is `index.html`; `landing.html` is a separate landing entry. Client bootstrapping and interaction wiring live in `src/js/app.js`, with presentation in `src/styles.css`.

#### Organization Catalog and Local Data
The application’s core domain model is the curated organization catalog, represented by `src/js/org.js`. It is supplemented by generated/static JSON artifacts for issue data, organization statistics, mentor data, and UI summaries:
- `data/issues.json`
- `data/org-stats.json`
- `data/ui-summary.json`

This boundary keeps primary discovery usable without live API availability while allowing data-refresh automation to update derived files.

#### Browser Application Layer
`src/js/app.js` owns the event-driven UI lifecycle: search, filtering, sorting, card rendering, modal behavior, compare selection, keyboard navigation, theme/preferences, and safe dynamic DOM rendering. It composes specialized feature modules:
- `src/js/githubAnalyzer.js`
- `src/js/recommender.js`
- `src/js/recommendation-ui.js`

User interactions transform catalog records plus local UI state into organization cards, detail dialogs, and a comparison view. Preferences and local analytics remain in browser `localStorage`; there is no account or central user database.

#### Matching and Recommendation Pipeline
Recommendation behavior is separated from base rendering. `src/js/skillExtractor.js` normalizes/extracts user skill context, while `src/js/recommender.js` scores organizations using skills, tags, competition, and experience-related signals. `src/js/recommendation-ui.js` presents the results. This makes the recommendation pipeline a client-only decision boundary: it consumes local catalog data and does not require the GitHub service.

#### GitHub Data Boundary
Live repository health and Good First Issue data flow from the browser through the Vercel Edge endpoint `api/github.js`, which proxies GitHub’s API and prevents exposing `GITHUB_TOKEN` to clients. It supports stats, Good First Issue counts, and bounded issue lists, with one-hour in-memory Edge caching. `src/js/githubAnalyzer.js` consumes this endpoint and enriches displayed organization data. GitHub availability/rate limits are isolated from baseline catalog browsing.

#### Offline and Deployment Runtime
The frontend is vanilla HTML/CSS/JavaScript with no framework, bundler, or application server. Vercel hosts static assets and runs the Edge Function, configured through `vercel.json`; `.env.example` documents required environment setup. `sw.js` provides offline resilience, using stale-while-revalidate for static assets and network-first behavior for API/JSON data. `manifest.json` supports installable/PWA-oriented browser metadata.

#### Data Maintenance and Governance Automation
Node scripts under `agent/scripts/` maintain generated datasets, validate organization URLs and mentor data, and collect GitHub-derived inputs; notable stages include `agent/scripts/fetch-issues.js`, `agent/scripts/generate-ui-cache.js`, and `agent/scripts/validate-generated-data.js`. A separate Python TENET review agent resides in `agent/tenet_agent/tenet_review.py`. GitHub Actions in `.github/workflows/` implement contribution intake, staged PR governance, mentor assignment/review tracking, and repository moderation; these are operational infrastructure rather than runtime application dependencies.

Main entry points: [`src/js/app.js`](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/app.js) (UI lifecycle), [`api/github.js`](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/api/github.js) (GitHub Edge proxy), [`index.html`](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/index.html) (Directory entry), [`src/js/recommender.js`](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/recommender.js) (Recommendation scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser App"]
  node_index["Directory entry<br/>HTML entry<br/>[index.html]"]
  node_landing["Landing entry<br/>HTML entry<br/>[landing.html]"]
  node_app["UI lifecycle<br/>browser controller<br/>[app.js]"]
  node_styles["Presentation<br/>CSS<br/>[styles.css]"]
  node_skills["Skill extraction<br/>client matcher<br/>[skillExtractor.js]"]
  node_recommender["Recommendation scoring<br/>client matcher<br/>[recommender.js]"]
  node_recommendation_ui["Recommendation UI<br/>browser view"]
  node_github_analyzer["GitHub analyzer<br/>browser client<br/>[githubAnalyzer.js]"]
  node_service_worker["Offline runtime<br/>service worker<br/>[sw.js]"]
  node_local_storage[("Browser preferences<br/>localStorage")]
end

subgraph group_data["Catalog Data"]
  node_catalog["Organization catalog<br/>domain model<br/>[org.js]"]
  node_issues["Issue data<br/>generated JSON<br/>[issues.json]"]
  node_org_stats["Organization stats<br/>generated JSON<br/>[org-stats.json]"]
  node_ui_summary["UI summaries<br/>generated JSON<br/>[ui-summary.json]"]
end

subgraph group_edge["GitHub Boundary"]
  node_github_api{{"GitHub Edge proxy<br/>Vercel Edge function<br/>[github.js]"}}
  node_github(("GitHub API<br/>external service"))
  node_vercel{{"Vercel deployment<br/>hosting runtime<br/>[vercel.json]"}}
end

subgraph group_automation["Maintenance &amp; Governance"]
  node_data_scripts["Dataset pipeline<br/>Node scripts"]
  node_tenet["TENET review agent<br/>Python review agent<br/>[tenet_review.py]"]
  node_workflows["PR governance<br/>GitHub Actions"]
end

node_index -->|"boots"| node_app
node_landing -->|"enters directory UI"| node_app
node_app -->|"presented by"| node_styles
node_app -->|"browses"| node_catalog
node_app -->|"uses local issue data"| node_issues
node_app -->|"uses local stats"| node_org_stats
node_app -->|"uses summaries"| node_ui_summary
node_app -->|"persists preferences"| node_local_storage
node_app -->|"collects skill context"| node_skills
node_skills -->|"normalized skills"| node_recommender
node_catalog -->|"organization signals"| node_recommender
node_recommender -->|"ranked results"| node_recommendation_ui
node_recommendation_ui -->|"renders into UI"| node_app
node_app -->|"requests enrichment"| node_github_analyzer
node_github_analyzer -->|"stats and issues"| node_github_api
node_github_api -->|"proxied API calls"| node_github
node_service_worker -.->|"caches static assets"| node_index
node_service_worker -.->|"network-first API"| node_github_api
node_vercel -->|"serves static app"| node_index
node_vercel -->|"runs"| node_github_api
node_data_scripts -->|"refreshes"| node_issues
node_data_scripts -->|"generates"| node_ui_summary
node_data_scripts -->|"updates"| node_org_stats
node_workflows -.->|"orchestrates maintenance"| node_data_scripts
node_workflows -.->|"uses review automation"| node_tenet

click node_index "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/index.html"
click node_landing "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/landing.html"
click node_app "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/app.js"
click node_styles "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/styles.css"
click node_catalog "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/org.js"
click node_issues "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/data/issues.json"
click node_org_stats "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/data/org-stats.json"
click node_ui_summary "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/data/ui-summary.json"
click node_skills "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/skillExtractor.js"
click node_recommender "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/recommender.js"
click node_recommendation_ui "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/recommendation-ui.js"
click node_github_analyzer "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/githubAnalyzer.js"
click node_github_api "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/api/github.js"
click node_service_worker "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/sw.js"
click node_vercel "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/vercel.json"
click node_tenet "https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/agent/tenet_agent/tenet_review.py"

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_index,node_landing,node_app,node_styles,node_skills,node_recommender,node_recommendation_ui,node_github_analyzer,node_service_worker,node_local_storage toneBlue
class node_catalog,node_issues,node_org_stats,node_ui_summary toneAmber
class node_github_api,node_github,node_vercel toneMint
class node_data_scripts,node_tenet,node_workflows toneRose
```

## Components

### Browser App

- [Directory entry](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/index.html): HTML entry · Primary organization discovery page. · `index.html`
- [Landing entry](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/landing.html): HTML entry · `landing.html`
- [UI lifecycle](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/app.js): browser controller · Owns search, filters, rendering, compare, modal, and preferences. · `src/js/app.js`
- [Presentation](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/styles.css): CSS · `src/styles.css`
- [Skill extraction](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/skillExtractor.js): client matcher · `src/js/skillExtractor.js`
- [Recommendation scoring](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/recommender.js): client matcher · Scores organizations from skills and catalog signals. · `src/js/recommender.js`
- [Recommendation UI](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/recommendation-ui.js): browser view · `src/js/recommendation-ui.js`
- [GitHub analyzer](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/githubAnalyzer.js): browser client · Enriches displayed organizations with live health and issue data. · `src/js/githubAnalyzer.js`
- [Offline runtime](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/sw.js): service worker · Uses stale-while-revalidate for assets and network-first for API/JSON. · `sw.js`
- **Browser preferences**: localStorage · Stores preferences and local analytics only.

### Catalog Data

- [Organization catalog](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/src/js/org.js): domain model · Curated source for baseline discovery. · `src/js/org.js`
- [Issue data](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/data/issues.json): generated JSON · `data/issues.json`
- [Organization stats](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/data/org-stats.json): generated JSON · `data/org-stats.json`
- [UI summaries](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/data/ui-summary.json): generated JSON · `data/ui-summary.json`

### GitHub Boundary

- [GitHub Edge proxy](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/api/github.js): Vercel Edge function · Protects token and caches GitHub responses for one hour. · `api/github.js`
- **GitHub API**: external service
- [Vercel deployment](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/vercel.json): hosting runtime · Hosts static assets and executes the Edge function. · `vercel.json`

### Maintenance & Governance

- **Dataset pipeline**: Node scripts · Fetches issues, generates UI cache, and validates generated data.
- [TENET review agent](https://github.com/s3dfx-cyber/gsoc-org-finder-/blob/main/agent/tenet_agent/tenet_review.py): Python review agent · `agent/tenet_agent/tenet_review.py`
- **PR governance**: GitHub Actions · Handles contribution intake, review tracking, and moderation.

## Connections

- Directory entry → UI lifecycle: boots
- Landing entry → UI lifecycle: enters directory UI
- UI lifecycle → Presentation: presented by
- UI lifecycle → Organization catalog: browses
- UI lifecycle → Issue data: uses local issue data
- UI lifecycle → Organization stats: uses local stats
- UI lifecycle → UI summaries: uses summaries
- UI lifecycle → Browser preferences: persists preferences
- UI lifecycle → Skill extraction: collects skill context
- Skill extraction → Recommendation scoring: normalized skills
- Organization catalog → Recommendation scoring: organization signals
- Recommendation scoring → Recommendation UI: ranked results
- Recommendation UI → UI lifecycle: renders into UI
- UI lifecycle → GitHub analyzer: requests enrichment
- GitHub analyzer → GitHub Edge proxy: stats and issues
- GitHub Edge proxy → GitHub API: proxied API calls
- Offline runtime → Directory entry: caches static assets
- Offline runtime → GitHub Edge proxy: network-first API
- Vercel deployment → Directory entry: serves static app
- Vercel deployment → GitHub Edge proxy: runs
- Dataset pipeline → Issue data: refreshes
- Dataset pipeline → UI summaries: generates
- Dataset pipeline → Organization stats: updates
- PR governance → Dataset pipeline: orchestrates maintenance
- PR governance → TENET review agent: uses review automation