# whoisyurii/checkmygit architecture

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

- Interactive diagram: https://gitdiagram.com/whoisyurii/checkmygit
- Repository: https://github.com/whoisyurii/checkmygit

## Overview

1. **Overall shape**
   - This is a **SvelteKit 2 / Svelte 5** app deployed to **Cloudflare Pages**.
   - It is not just a marketing site: it has a public landing experience, a per-user portfolio generator, “explore” analytics pages, and several JSON/image API endpoints.

2. **Primary product flow: GitHub username → portfolio**
   - The core experience lives under `src/routes/[username]`.
   - A request for a username is handled by `+page.server.ts`, which fetches and shapes GitHub data, then `+page.svelte` renders one of several templates.
   - The portfolio is composed from reusable sections in `src/lib/components/portfolio` and `src/lib/components/templates`, with the selected template controlled by query state such as `template=bento`.

3. **GitHub data access layer**
   - `src/lib/server/github.ts` is the main integration boundary with GitHub.
   - The README says GitHub **GraphQL is the primary source**, with **REST fallback** when needed.
   - Shared data shapes live in `src/lib/types/github.ts`, `portfolio.ts`, `rankings.ts`, `trending.ts`, and `globe.ts`, which indicates the app normalizes external API data before it reaches UI components.

4. **Server-side feature modules**
   - The `src/lib/server` directory contains most of the app’s business logic:
     - `rankings.ts` and `trending.ts` back the public rankings/trending features.
     - `globe.ts` and `geo/*` support location-based visualization, including geocoding and country centroid lookup.
     - `kv/*` provides Cloudflare KV-backed caching, deduplication, retry logic, and counters.
   - This separation makes the server layer the boundary for rate-limit-sensitive and cache-sensitive operations.

5. **Caching, counters, and persistence on Cloudflare**
   - The `src/lib/server/kv` submodule strongly suggests the app uses **Cloudflare KV** for lightweight persistence.
   - It appears to support:
     - cached API responses,
     - deduplicating repeated events,
     - global/view counters,
     - retry helpers for external calls.
   - This is important architecturally because it reduces GitHub API pressure and enables aggregate metrics such as views and global counters.

6. **Public API surface**
   - `src/routes/api/*` exposes backend functionality to the browser and to external consumers:
     - `/api/rankings`
     - `/api/trending`
     - `/api/view`
     - `/api/og/[username]`
   - These endpoints likely reuse the same server modules as the page loaders, so the app has a shared data layer serving both HTML and JSON/image responses.

7. **Explore subsystem**
   - `src/routes/explore` is a dedicated analytics/discovery area with subpages for:
     - `globe`
     - `rankings`
     - `trending`
   - Each has its own `+page.server.ts`, so the explore views are server-rendered and data-driven rather than purely client-side.
   - UI components under `src/lib/components/explore`, `rankings`, and `globe` suggest these pages are built from table/filter/chart widgets and, for the globe, geographic visualization.

8. **Landing, marketing, and navigation**
   - The root route (`src/routes/+page.svelte`) and `src/lib/components/landing/*` implement the homepage: hero, feature highlights, screenshot showcase, and CTA.
   - Shared layout pieces in `src/lib/components/layout` provide the header/footer, logo, search, actions, and controls.
   - The header likely acts as the main navigation entry point into username lookup and explore pages.

9. **Reusable UI kit**
   - `src/lib/components/ui` contains the low-level design system: buttons, cards, badges, inputs, dropdowns, skeletons, tabs, toast, theme toggle, QR modal, and table primitives.
   - This is the styling and interaction foundation used across landing, portfolio, rankings, and explore pages.
   - The presence of `LoadingTransition`, `Skeleton`, and multiple `*Skeleton.svelte` components indicates the app is designed around asynchronous server data with polished loading states.

10. **Portfolio export and sharing**
   - `src/lib/components/export` and `src/lib/utils/export.ts` support turning a rendered portfolio into an image.
   - The README explicitly calls out **PNG export** via `html-to-image`.
   - `QRModal` and the shareable URL pattern suggest the app is optimized for link sharing and image capture, not just on-screen viewing.

11. **Client-side state and presentation helpers**
   - `src/lib/stores/*` contains Svelte stores for navigation, theme, GitHub stars, and generation state.
   - These stores are the main client-side state boundary; they keep cross-component UI state out of the server loaders.
   - `src/lib/utils/*` contains pure helpers for GitHub data transformation, JSON-LD generation, QR encoding, and export support.

12. **SEO, metadata, and static delivery**
   - `src/routes/sitemap.xml/+server.ts` and `src/lib/utils/jsonld.ts` show SEO is treated as a first-class concern.
   - Static files in `static/` include `robots.txt` and a web manifest, reinforcing that the app is optimized for discoverability and PWA-style presentation.
   - The OG image endpoint under `/api/og/[username]` also supports social sharing previews.

13. **Deployment/runtime boundary**
   - The presence of `wrangler.toml` and Cloudflare-specific KV modules indicates the app is designed to run in a **Cloudflare edge/serverless environment**.
   - That choice materially shapes the architecture: lightweight server functions, external API calls, and KV-based caching/persistence instead of a traditional long-lived backend.

14. **How to draw the diagram**
   - A useful diagram should show:
     - browser requests entering SvelteKit routes,
     - server loaders/API endpoints calling GitHub and geo services,
     - Cloudflare KV sitting behind caching/counters,
     - shared UI components rendering landing, portfolio, and explore pages,
     - export/share endpoints producing PNG/OG assets.
   - The main architectural boundary is **presentation (Svelte components/routes)** versus **server data orchestration (`src/lib/server` + API routes + KV + GitHub)**.

Main entry points: [`src/lib/server/github.ts`](https://github.com/whoisyurii/checkmygit/blob/main/src/lib/server/github.ts) (GitHub), [`src/routes/[username]/+page.svelte`](https://github.com/whoisyurii/checkmygit/blob/main/src/routes/[username]/+page.svelte) (Portfolio route), [`src/lib/components/ui`](https://github.com/whoisyurii/checkmygit/tree/main/src/lib/components/ui) (UI kit), [`src/routes/explore/+layout.svelte`](https://github.com/whoisyurii/checkmygit/blob/main/src/routes/explore/+layout.svelte) (Explore)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_app_shell["App shell<br/>SvelteKit root<br/>[+layout.svelte]"]
  node_home_page["Home<br/>landing page<br/>[+page.svelte]"]
  node_username_route["Portfolio route<br/>per-user page<br/>[+page.svelte]"]
  node_explore_area["Explore<br/>analytics pages<br/>[+layout.svelte]"]
  node_explore_globe_page["Globe page<br/>geo analytics<br/>[+page.svelte]"]
  node_explore_rankings_page["Rankings page<br/>ranked lists<br/>[+page.svelte]"]
  node_explore_trending_page["Trending page<br/>trend lists<br/>[+page.svelte]"]
end

subgraph group_server["Server/Data"]
  node_github_integration[("GitHub<br/>API boundary<br/>[github.ts]")]
  node_rankings_logic["Rankings<br/>aggregation<br/>[rankings.ts]"]
  node_trending_logic["Trending<br/>aggregation<br/>[trending.ts]"]
  node_globe_logic["Globe data<br/>geo pipeline<br/>[globe.ts]"]
  node_kv_layer[("KV layer<br/>cache/counter store")]
  node_geo_helpers["Geo helpers<br/>geocoding"]
end

subgraph group_shared["Shared UI"]
  node_portfolio_ui["Portfolio UI<br/>profile sections"]
  node_templates["Templates<br/>portfolio variants"]
  node_landing_ui["Landing UI<br/>homepage components"]
  node_layout_ui["Layout UI<br/>navigation chrome"]
  node_ui_kit["UI kit<br/>design system"]
  node_state_utils["State + utils<br/>client helpers"]
end

subgraph group_delivery["Delivery/SEO"]
  node_api_surface["API routes<br/>JSON/image endpoints"]
  node_og_endpoint["OG image<br/>share preview<br/>[+server.ts]"]
  node_sitemap["Sitemap<br/>seo endpoint<br/>[+server.ts]"]
end

node_app_shell -->|"renders"| node_home_page
node_app_shell -->|"renders"| node_username_route
node_app_shell -->|"renders"| node_explore_area
node_home_page -->|"uses"| node_landing_ui
node_home_page -->|"uses"| node_layout_ui
node_username_route -->|"uses"| node_portfolio_ui
node_username_route -->|"selects"| node_templates
node_username_route -->|"loads"| node_github_integration
node_username_route -.->|"shares state"| node_state_utils
node_explore_area -->|"contains"| node_explore_globe_page
node_explore_area -->|"contains"| node_explore_rankings_page
node_explore_area -->|"contains"| node_explore_trending_page
node_explore_globe_page -->|"loads"| node_globe_logic
node_explore_globe_page -->|"uses"| node_geo_helpers
node_explore_rankings_page -->|"loads"| node_rankings_logic
node_explore_trending_page -->|"loads"| node_trending_logic
node_api_surface -->|"serves"| node_rankings_logic
node_api_surface -->|"serves"| node_trending_logic
node_api_surface -->|"persists"| node_kv_layer
node_og_endpoint -->|"loads"| node_github_integration
node_sitemap -.->|"uses"| node_state_utils
node_github_integration -->|"caches"| node_kv_layer
node_rankings_logic -->|"queries"| node_github_integration
node_trending_logic -->|"queries"| node_github_integration
node_globe_logic -->|"queries"| node_github_integration
node_globe_logic -->|"uses"| node_geo_helpers
node_portfolio_ui -->|"built from"| node_ui_kit
node_templates -->|"built from"| node_ui_kit
node_landing_ui -->|"built from"| node_ui_kit
node_layout_ui -->|"built from"| node_ui_kit
node_state_utils -.->|"supports"| node_ui_kit

click node_app_shell "https://github.com/whoisyurii/checkmygit/blob/main/src/routes/+layout.svelte"
click node_home_page "https://github.com/whoisyurii/checkmygit/blob/main/src/routes/+page.svelte"
click node_username_route "https://github.com/whoisyurii/checkmygit/blob/main/src/routes/[username]/+page.svelte"
click node_explore_area "https://github.com/whoisyurii/checkmygit/blob/main/src/routes/explore/+layout.svelte"
click node_explore_globe_page "https://github.com/whoisyurii/checkmygit/blob/main/src/routes/explore/globe/+page.svelte"
click node_explore_rankings_page "https://github.com/whoisyurii/checkmygit/blob/main/src/routes/explore/rankings/+page.svelte"
click node_explore_trending_page "https://github.com/whoisyurii/checkmygit/blob/main/src/routes/explore/trending/+page.svelte"
click node_api_surface "https://github.com/whoisyurii/checkmygit/tree/main/src/routes/api"
click node_og_endpoint "https://github.com/whoisyurii/checkmygit/blob/main/src/routes/api/og/[username]/+server.ts"
click node_sitemap "https://github.com/whoisyurii/checkmygit/blob/main/src/routes/sitemap.xml/+server.ts"
click node_github_integration "https://github.com/whoisyurii/checkmygit/blob/main/src/lib/server/github.ts"
click node_rankings_logic "https://github.com/whoisyurii/checkmygit/blob/main/src/lib/server/rankings.ts"
click node_trending_logic "https://github.com/whoisyurii/checkmygit/blob/main/src/lib/server/trending.ts"
click node_globe_logic "https://github.com/whoisyurii/checkmygit/blob/main/src/lib/server/globe.ts"
click node_kv_layer "https://github.com/whoisyurii/checkmygit/tree/main/src/lib/server/kv"
click node_geo_helpers "https://github.com/whoisyurii/checkmygit/tree/main/src/lib/server/geo"
click node_portfolio_ui "https://github.com/whoisyurii/checkmygit/tree/main/src/lib/components/portfolio"
click node_templates "https://github.com/whoisyurii/checkmygit/tree/main/src/lib/components/templates"
click node_landing_ui "https://github.com/whoisyurii/checkmygit/tree/main/src/lib/components/landing"
click node_layout_ui "https://github.com/whoisyurii/checkmygit/tree/main/src/lib/components/layout"
click node_ui_kit "https://github.com/whoisyurii/checkmygit/tree/main/src/lib/components/ui"
click node_state_utils "https://github.com/whoisyurii/checkmygit/tree/main/src/lib/stores"

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_app_shell,node_home_page,node_username_route,node_explore_area,node_explore_globe_page,node_explore_rankings_page,node_explore_trending_page toneBlue
class node_github_integration,node_rankings_logic,node_trending_logic,node_globe_logic,node_kv_layer,node_geo_helpers toneAmber
class node_portfolio_ui,node_templates,node_landing_ui,node_layout_ui,node_ui_kit,node_state_utils toneMint
class node_api_surface,node_og_endpoint,node_sitemap toneRose
```

## Components

### Presentation

Routes and UI layers rendered for users

- [App shell](https://github.com/whoisyurii/checkmygit/blob/main/src/routes/+layout.svelte): SvelteKit root · Global layout, error handling, and app entrypoints · `src/routes/+layout.svelte`
- [Home](https://github.com/whoisyurii/checkmygit/blob/main/src/routes/+page.svelte): landing page · Public landing experience and CTA · `src/routes/+page.svelte`
- [Portfolio route](https://github.com/whoisyurii/checkmygit/blob/main/src/routes/[username]/+page.svelte): per-user page · Username-driven portfolio generation and rendering · `src/routes/[username]/+page.svelte`
- [Explore](https://github.com/whoisyurii/checkmygit/blob/main/src/routes/explore/+layout.svelte): analytics pages · Server-rendered discovery area for globe, rankings, and trending · `src/routes/explore/+layout.svelte`
- [Globe page](https://github.com/whoisyurii/checkmygit/blob/main/src/routes/explore/globe/+page.svelte): geo analytics · Geographic exploration view with server data · `src/routes/explore/globe/+page.svelte`
- [Rankings page](https://github.com/whoisyurii/checkmygit/blob/main/src/routes/explore/rankings/+page.svelte): ranked lists · Server-rendered rankings view · `src/routes/explore/rankings/+page.svelte`
- [Trending page](https://github.com/whoisyurii/checkmygit/blob/main/src/routes/explore/trending/+page.svelte): trend lists · Server-rendered trending view · `src/routes/explore/trending/+page.svelte`

### Server/Data

GitHub, geo, ranking, trending, and KV orchestration

- [GitHub](https://github.com/whoisyurii/checkmygit/blob/main/src/lib/server/github.ts): API boundary · Primary GitHub GraphQL integration with REST fallback · `src/lib/server/github.ts`
- [Rankings](https://github.com/whoisyurii/checkmygit/blob/main/src/lib/server/rankings.ts): aggregation · Ranking computations and data shaping · `src/lib/server/rankings.ts`
- [Trending](https://github.com/whoisyurii/checkmygit/blob/main/src/lib/server/trending.ts): aggregation · Trending computations and data shaping · `src/lib/server/trending.ts`
- [Globe data](https://github.com/whoisyurii/checkmygit/blob/main/src/lib/server/globe.ts): geo pipeline · Location data preparation for globe visualization · `src/lib/server/globe.ts`
- [KV layer](https://github.com/whoisyurii/checkmygit/tree/main/src/lib/server/kv): cache/counter store · Cloudflare KV-backed caching, deduplication, retries, and counters · `src/lib/server/kv`
- [Geo helpers](https://github.com/whoisyurii/checkmygit/tree/main/src/lib/server/geo): geocoding · Country centroids and geocoding support · `src/lib/server/geo`

### Shared UI

Reusable components, templates, stores, and helpers

- [Portfolio UI](https://github.com/whoisyurii/checkmygit/tree/main/src/lib/components/portfolio): profile sections · Reusable portfolio sections and templates · `src/lib/components/portfolio`
- [Templates](https://github.com/whoisyurii/checkmygit/tree/main/src/lib/components/templates): portfolio variants · Alternative portfolio layouts such as Bento, GitHub, and Minimal · `src/lib/components/templates`
- [Landing UI](https://github.com/whoisyurii/checkmygit/tree/main/src/lib/components/landing): homepage components · Hero, features, showcase, and CTA modules · `src/lib/components/landing`
- [Layout UI](https://github.com/whoisyurii/checkmygit/tree/main/src/lib/components/layout): navigation chrome · Header, footer, logo, search, and controls · `src/lib/components/layout`
- [UI kit](https://github.com/whoisyurii/checkmygit/tree/main/src/lib/components/ui): design system · Buttons, cards, inputs, tables, skeletons, modals, theme, and feedback primitives · `src/lib/components/ui`
- [State + utils](https://github.com/whoisyurii/checkmygit/tree/main/src/lib/stores): client helpers · Svelte stores and pure helpers for export, transforms, JSON-LD, and QR · `src/lib/stores`

### Delivery/SEO

Public endpoints and static discoverability assets

- [API routes](https://github.com/whoisyurii/checkmygit/tree/main/src/routes/api): JSON/image endpoints · Shared backend surface for rankings, trending, views, and OG images · `src/routes/api`
- [OG image](https://github.com/whoisyurii/checkmygit/blob/main/src/routes/api/og/[username]/+server.ts): share preview · Open Graph image generation for usernames · `src/routes/api/og/[username]/+server.ts`
- [Sitemap](https://github.com/whoisyurii/checkmygit/blob/main/src/routes/sitemap.xml/+server.ts): seo endpoint · XML sitemap generation · `src/routes/sitemap.xml/+server.ts`

## Connections

- App shell → Home: renders · Root layout wraps the landing page and shared chrome
- App shell → Portfolio route: renders · Root layout participates in per-username page rendering
- App shell → Explore: renders · Root layout provides shell for explore routes
- Home → Landing UI: uses · Landing page is composed from landing sections
- Home → Layout UI: uses · Homepage shares header/footer/navigation
- Portfolio route → Portfolio UI: uses · Portfolio page is assembled from profile and section components
- Portfolio route → Templates: selects · Template choice controls portfolio layout
- Portfolio route → GitHub: loads · Server loader fetches and shapes GitHub data
- Portfolio route → State + utils: shares state · Client-side generation and export helpers support the page
- Explore → Globe page: contains · Explore area routes to globe subpage
- Explore → Rankings page: contains · Explore area routes to rankings subpage
- Explore → Trending page: contains · Explore area routes to trending subpage
- Globe page → Globe data: loads · Globe page uses server-side geo aggregation
- Globe page → Geo helpers: uses · Geocoding and centroid helpers support map data
- Rankings page → Rankings: loads · Rankings page uses ranking aggregation
- Trending page → Trending: loads · Trending page uses trending aggregation
- API routes → Rankings: serves · Rankings JSON endpoint reuses server ranking logic
- API routes → Trending: serves · Trending JSON endpoint reuses server trending logic
- API routes → KV layer: persists · View and aggregate endpoints depend on KV caching/counters
- OG image → GitHub: loads · OG image generation needs user profile data
- Sitemap → State + utils: uses · SEO helpers and metadata generation support static discovery
- GitHub → KV layer: caches · GitHub access is rate-limit sensitive and cache-backed
- Rankings → GitHub: queries · Ranking data is derived from GitHub data
- Trending → GitHub: queries · Trending data is derived from GitHub data
- Globe data → GitHub: queries · Globe visualization is built from GitHub/user location data
- Globe data → Geo helpers: uses · Geographic normalization depends on helper data
- Portfolio UI → UI kit: built from · Portfolio sections use shared UI primitives
- Templates → UI kit: built from · Template variants rely on the same design system
- Landing UI → UI kit: built from · Landing sections use shared UI primitives
- Layout UI → UI kit: built from · Header and footer use shared UI primitives
- State + utils → UI kit: supports · Export, QR, and toast-like interactions depend on UI helpers