# venkatesh0214/knowaiedge architecture

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

- Interactive diagram: https://gitdiagram.com/venkatesh0214/knowaiedge
- Repository: https://github.com/venkatesh0214/knowaiedge

## Overview

knowAIedge is an educational AI publishing site with news, category-aware GitHub rankings, a YouTube watchlist, and an admin Model Radar. Visitors browse the site; editors can publish or refresh content through admin APIs or the stateless MCP editor, with ChatGPT identity and an owner allowlist guarding privileged operations. R2-backed news, activity, and reading history are visible in sampled routes; repository and model data modules provide ranking and radar operations. The README documents YouTube discovery and D1/R2 hosting, but their full runtime wiring is not sampled.

Main entry points: [`app/page.tsx`](https://github.com/venkatesh0214/knowaiedge/blob/main/app/page.tsx) (Site experience), [`app/mcp/route.ts`](https://github.com/venkatesh0214/knowaiedge/blob/main/app/mcp/route.ts) (MCP editor), [`app/repository-data.ts`](https://github.com/venkatesh0214/knowaiedge/blob/main/app/repository-data.ts) (Ranking data), [`app/admin-access.ts`](https://github.com/venkatesh0214/knowaiedge/blob/main/app/admin-access.ts) (Admin access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Site experience"]
  node_site["Site experience<br/>[page.tsx]"]
end

subgraph group_content["Content features"]
  node_news_ui["News browsing<br/>[explorer.tsx]"]
  node_feed_controls["Feed controls<br/>[feed-controls.tsx]"]
  node_repositories_ui["Repository rankings<br/>[repositories.tsx]"]
  node_repo_data["Ranking data<br/>[repository-data.ts]"]
  node_repo_scoring["Ranking scores"]
  node_watchlist_ui["AI watchlist<br/>[watchlist.tsx]"]
  node_watchlist_data["Watchlist data<br/>[watchlist-data.ts]"]
  node_radar_ui["Model Radar<br/>[model-radar.tsx]"]
  node_model_data["Model data<br/>[model-data.ts]"]
  node_activity_route["Activity and opens<br/>[route.ts]"]
  node_open_route["Article opening<br/>[route.ts]"]
  node_history_route["Reading history<br/>[route.ts]"]
  node_news_route["News API<br/>[route.ts]"]
end

subgraph group_editor["Editor and identity"]
  node_mcp["MCP editor<br/>[route.ts]"]
  node_models_api["Model API<br/>[route.ts]"]
  node_repositories_api["Repository API<br/>[route.ts]"]
  node_admin_access["Admin access<br/>[admin-access.ts]"]
  node_chatgpt_auth["ChatGPT identity<br/>[chatgpt-auth.ts]"]
end

subgraph group_state["Data and services"]
  node_r2[("Cloudflare R2")]
  node_github["GitHub API"]
  node_youtube["YouTube discovery"]
  node_hosting["Cloudflare hosting"]
end

node_visitor(("Visitor"))
node_editor_actor(("Site editor"))

node_visitor -->|"browses"| node_site
node_site -->|"renders"| node_news_ui
node_site -->|"renders"| node_repositories_ui
node_site -->|"renders"| node_watchlist_ui
node_site -->|"renders"| node_radar_ui
node_site -->|"fetches"| node_news_route
node_site -->|"records activity"| node_activity_route
node_site -->|"loads history"| node_history_route
node_site -->|"opens articles"| node_open_route
node_site -->|"uses"| node_feed_controls
node_repositories_ui -->|"uses"| node_feed_controls
node_repositories_ui -->|"uses"| node_repo_scoring
node_repo_data -->|"ranks with"| node_repo_scoring
node_repositories_api -->|"serves"| node_repo_data
node_repo_data -.->|"queries"| node_github
node_watchlist_ui -.->|"loads"| node_watchlist_data
node_watchlist_data -.->|"discovers"| node_youtube
node_radar_ui -->|"loads"| node_model_data
node_models_api -->|"calls"| node_model_data
node_news_route -->|"reads and writes"| node_r2
node_activity_route -->|"records and lists"| node_r2
node_open_route -->|"records opens"| node_activity_route
node_open_route -->|"reads history"| node_r2
node_history_route -.->|"reads history"| node_r2
node_editor_actor -->|"invokes tools"| node_mcp
node_mcp -->|"calls"| node_watchlist_data
node_mcp -->|"calls"| node_model_data
node_mcp -->|"calls"| node_repo_data
node_mcp -->|"calls"| node_news_route
node_mcp -->|"checks access"| node_admin_access
node_models_api -->|"checks access"| node_admin_access
node_admin_access -->|"gets identity"| node_chatgpt_auth
node_admin_access -->|"authorizes"| node_editor_actor
node_hosting -.->|"provides binding"| node_r2
node_hosting -.->|"stores content"| node_r2

click node_site "https://github.com/venkatesh0214/knowaiedge/blob/main/app/page.tsx"
click node_news_ui "https://github.com/venkatesh0214/knowaiedge/blob/main/app/explorer.tsx"
click node_feed_controls "https://github.com/venkatesh0214/knowaiedge/blob/main/app/feed-controls.tsx"
click node_repositories_ui "https://github.com/venkatesh0214/knowaiedge/blob/main/app/repositories.tsx"
click node_repo_data "https://github.com/venkatesh0214/knowaiedge/blob/main/app/repository-data.ts"
click node_repo_scoring "https://github.com/venkatesh0214/knowaiedge/blob/main/app/repository-scoring.ts"
click node_watchlist_ui "https://github.com/venkatesh0214/knowaiedge/blob/main/app/watchlist.tsx"
click node_watchlist_data "https://github.com/venkatesh0214/knowaiedge/blob/main/app/watchlist-data.ts"
click node_radar_ui "https://github.com/venkatesh0214/knowaiedge/blob/main/app/model-radar.tsx"
click node_model_data "https://github.com/venkatesh0214/knowaiedge/blob/main/app/model-data.ts"
click node_activity_route "https://github.com/venkatesh0214/knowaiedge/blob/main/app/api/activity/route.ts"
click node_open_route "https://github.com/venkatesh0214/knowaiedge/blob/main/app/api/open/route.ts"
click node_history_route "https://github.com/venkatesh0214/knowaiedge/blob/main/app/api/history/route.ts"
click node_news_route "https://github.com/venkatesh0214/knowaiedge/blob/main/app/api/news/route.ts"
click node_mcp "https://github.com/venkatesh0214/knowaiedge/blob/main/app/mcp/route.ts"
click node_models_api "https://github.com/venkatesh0214/knowaiedge/blob/main/app/api/models/route.ts"
click node_repositories_api "https://github.com/venkatesh0214/knowaiedge/blob/main/app/api/repositories/route.ts"
click node_admin_access "https://github.com/venkatesh0214/knowaiedge/blob/main/app/admin-access.ts"
click node_chatgpt_auth "https://github.com/venkatesh0214/knowaiedge/blob/main/app/chatgpt-auth.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_site toneBlue
class node_news_ui,node_feed_controls,node_repositories_ui,node_repo_data,node_repo_scoring,node_watchlist_ui,node_watchlist_data,node_radar_ui,node_model_data,node_activity_route,node_open_route,node_history_route,node_news_route toneAmber
class node_mcp,node_models_api,node_repositories_api,node_admin_access,node_chatgpt_auth toneMint
class node_r2,node_github,node_youtube,node_hosting toneRose
class node_visitor,node_editor_actor toneIndigo
```

## Components

### Site experience

- [Site experience](https://github.com/venkatesh0214/knowaiedge/blob/main/app/page.tsx): `app/page.tsx`

### Content features

- [News browsing](https://github.com/venkatesh0214/knowaiedge/blob/main/app/explorer.tsx): `app/explorer.tsx`
- [Feed controls](https://github.com/venkatesh0214/knowaiedge/blob/main/app/feed-controls.tsx): `app/feed-controls.tsx`
- [Repository rankings](https://github.com/venkatesh0214/knowaiedge/blob/main/app/repositories.tsx): `app/repositories.tsx`
- [Ranking data](https://github.com/venkatesh0214/knowaiedge/blob/main/app/repository-data.ts): `app/repository-data.ts`
- [Ranking scores](https://github.com/venkatesh0214/knowaiedge/blob/main/app/repository-scoring.ts): `app/repository-scoring.ts`
- [AI watchlist](https://github.com/venkatesh0214/knowaiedge/blob/main/app/watchlist.tsx): `app/watchlist.tsx`
- [Watchlist data](https://github.com/venkatesh0214/knowaiedge/blob/main/app/watchlist-data.ts): `app/watchlist-data.ts`
- [Model Radar](https://github.com/venkatesh0214/knowaiedge/blob/main/app/model-radar.tsx): `app/model-radar.tsx`
- [Model data](https://github.com/venkatesh0214/knowaiedge/blob/main/app/model-data.ts): `app/model-data.ts`
- [Activity and opens](https://github.com/venkatesh0214/knowaiedge/blob/main/app/api/activity/route.ts): `app/api/activity/route.ts`
- [Article opening](https://github.com/venkatesh0214/knowaiedge/blob/main/app/api/open/route.ts): `app/api/open/route.ts`
- [Reading history](https://github.com/venkatesh0214/knowaiedge/blob/main/app/api/history/route.ts): `app/api/history/route.ts`
- [News API](https://github.com/venkatesh0214/knowaiedge/blob/main/app/api/news/route.ts): `app/api/news/route.ts`

### Editor and identity

- [MCP editor](https://github.com/venkatesh0214/knowaiedge/blob/main/app/mcp/route.ts): `app/mcp/route.ts`
- [Model API](https://github.com/venkatesh0214/knowaiedge/blob/main/app/api/models/route.ts): `app/api/models/route.ts`
- [Repository API](https://github.com/venkatesh0214/knowaiedge/blob/main/app/api/repositories/route.ts): `app/api/repositories/route.ts`
- [Admin access](https://github.com/venkatesh0214/knowaiedge/blob/main/app/admin-access.ts): `app/admin-access.ts`
- [ChatGPT identity](https://github.com/venkatesh0214/knowaiedge/blob/main/app/chatgpt-auth.ts): `app/chatgpt-auth.ts`

### Data and services

- **Cloudflare R2**
- **GitHub API**
- **YouTube discovery**
- **Cloudflare hosting**

### Other components

- **Visitor**
- **Site editor**

## Connections

- Visitor → Site experience: browses (evidence: `app/page.tsx`)
- Site experience → News browsing: renders (evidence: `app/page.tsx`)
- Site experience → Repository rankings: renders (evidence: `app/page.tsx`)
- Site experience → AI watchlist: renders (evidence: `app/page.tsx`)
- Site experience → Model Radar: renders (evidence: `app/page.tsx`)
- Site experience → News API: fetches (evidence: `app/page.tsx`)
- Site experience → Activity and opens: records activity (evidence: `app/page.tsx`)
- Site experience → Reading history: loads history (evidence: `app/page.tsx`)
- Site experience → Article opening: opens articles (evidence: `app/page.tsx`)
- Site experience → Feed controls: uses (evidence: `app/page.tsx`)
- Repository rankings → Feed controls: uses (evidence: `app/repositories.tsx`)
- Repository rankings → Ranking scores: uses (evidence: `app/repositories.tsx`)
- Ranking data → Ranking scores: ranks with (evidence: `app/repository-data.ts`)
- Repository API → Ranking data: serves (evidence: `app/api/repositories/route.ts`)
- Ranking data → GitHub API: queries (evidence: `app/repository-data.ts`)
- AI watchlist → Watchlist data: loads
- Watchlist data → YouTube discovery: discovers
- Model Radar → Model data: loads (evidence: `app/model-radar.tsx`)
- Model API → Model data: calls (evidence: `app/api/models/route.ts`)
- News API → Cloudflare R2: reads and writes (evidence: `app/api/news/route.ts`)
- Activity and opens → Cloudflare R2: records and lists (evidence: `app/api/activity/route.ts`)
- Article opening → Activity and opens: records opens (evidence: `app/api/open/route.ts`)
- Article opening → Cloudflare R2: reads history (evidence: `app/api/open/route.ts`)
- Reading history → Cloudflare R2: reads history
- Site editor → MCP editor: invokes tools (evidence: `app/mcp/route.ts`)
- MCP editor → Watchlist data: calls (evidence: `app/mcp/route.ts`)
- MCP editor → Model data: calls (evidence: `app/mcp/route.ts`)
- MCP editor → Ranking data: calls (evidence: `app/mcp/route.ts`)
- MCP editor → News API: calls (evidence: `app/mcp/route.ts`)
- MCP editor → Admin access: checks access (evidence: `app/mcp/route.ts`)
- Model API → Admin access: checks access (evidence: `app/api/models/route.ts`)
- Admin access → ChatGPT identity: gets identity (evidence: `app/admin-access.ts`)
- Admin access → Site editor: authorizes (evidence: `app/admin-access.ts`)
- Cloudflare hosting → Cloudflare R2: provides binding
- Cloudflare hosting → Cloudflare R2: stores content