# blitzbugg/gitprix architecture

> Architecture diagram of the GitHub repository blitzbugg/gitprix, 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/blitzbugg/gitprix
- Repository: https://github.com/blitzbugg/gitprix

## Overview

#### Purpose and Runtime

GitPrix is a client-facing Next.js App Router application that converts a public GitHub username into a motorsport-style collectible driver card. It runs as a single-page experience, with a server-side route acting as a narrow proxy to GitHub’s public Users API. No authentication, persistence layer, or database is present.

Primary entry points:
- `app/page.tsx` — application page and experience host.
- `app/layout.tsx` — root document/layout boundary.
- `app/api/github/[username]/route.ts` — GitHub profile lookup endpoint.

#### Experience Orchestration

The main interactive flow is concentrated in the page-level experience component. It accepts username input, drives intro/loading/error/success states, coordinates profile fetching, and exposes export/share actions once a card is assembled.

Core paths:
- `app/page.tsx`
- `components/gitprix-experience.tsx`
- `app/globals.css`

The UI is designed as an immersive night-race scene rather than a conventional dashboard; motion and reduced-motion behavior are part of the product experience.

#### GitHub Data Boundary

Browser code requests the internal dynamic API route instead of directly calling GitHub. The route resolves `/api/github/:username`, fetches public profile fields from GitHub, and returns data or an error response to the experience layer.

Core paths:
- `app/api/github/[username]/route.ts`
- `types/github.ts`
- `components/gitprix-experience.tsx`

This boundary centralizes external-service handling and keeps GitHub API URL/error semantics out of the presentation layer. It is subject to GitHub unauthenticated rate limits.

#### Rating and Domain Model

GitHub profile data is transformed into a driver-oriented domain model with deterministic ratings: pace, consistency, reliability, experience, versatility, and teamwork. Scores derive from public profile signals—including repository count, account age, followers/following—and a username-derived stable seed.

Core paths:
- `lib/driver.ts`
- `types/github.ts`
- `components/driver-card.tsx`

`lib/driver.ts` is the principal business-logic boundary: equivalent public profile inputs should yield equivalent driver-card values.

#### Visual Composition and Card Rendering

The collectible card is a distinct renderable artifact, composed from profile-derived driver data and embedded in a motorsport environment. The scene supplies circuit/stadium/pit-wall atmosphere, while the card owns the information-dense driver presentation and interactive tilt.

Core paths:
- `components/driver-card.tsx`
- `components/ambient-scene.tsx`
- `components/gitprix-experience.tsx`

Framer Motion and GSAP support animation/interaction; Tailwind CSS and global CSS provide styling.

#### Export and Sharing Output

The completed card can be rasterized into a high-resolution PNG via `html-to-image`. That generated image is used for download and, where browser support allows, native file sharing. X and Reddit use browser URL-based sharing flows; unsupported native image-sharing cases fall back to download.

Core paths:
- `components/gitprix-experience.tsx`
- `components/driver-card.tsx`

This is a browser capability boundary: image generation and native sharing occur client-side after the card is rendered.

#### Metadata and Deployment Surface

The app provides Next.js-generated icons, social images, robots, and sitemap endpoints for discoverability and link previews.

Core paths:
- `app/opengraph-image.tsx`
- `app/twitter-image.tsx`
- `app/sitemap.ts`

Infrastructure is standard Next.js/Node.js build and serving, configured through `next.config.ts`; the only named external data service is GitHub’s public API.

Main entry points: [`components/gitprix-experience.tsx`](https://github.com/blitzbugg/gitprix/blob/master/components/gitprix-experience.tsx) (GitPrix experience), [`app/page.tsx`](https://github.com/blitzbugg/gitprix/blob/master/app/page.tsx) (Application page), [`app/api/github/[username]/route.ts`](https://github.com/blitzbugg/gitprix/blob/master/app/api/github/%5Busername%5D/route.ts) (Profile lookup route), [`components/driver-card.tsx`](https://github.com/blitzbugg/gitprix/blob/master/components/driver-card.tsx) (Driver card)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser Experience"]
  node_experience["GitPrix experience<br/>client orchestrator"]
  node_styles["Global styling<br/>CSS<br/>[globals.css]"]
  node_ambient["Ambient scene<br/>visual component<br/>[ambient-scene.tsx]"]
  node_card["Driver card<br/>renderable component<br/>[driver-card.tsx]"]
  node_export["PNG export and sharing<br/>browser capability"]
end

subgraph group_server["Next.js Server"]
  node_layout["Root layout<br/>Next.js layout<br/>[layout.tsx]"]
  node_page["Application page<br/>App Router page<br/>[page.tsx]"]
  node_github_route["Profile lookup route<br/>API route<br/>[route.ts]"]
  node_github_types["GitHub profile types<br/>data contract<br/>[github.ts]"]
  node_driver_model{{"Driver ratings<br/>domain logic<br/>[driver.ts]"}}
  node_og_image["Open Graph image<br/>metadata route"]
  node_twitter_image["Twitter image<br/>metadata route<br/>[twitter-image.tsx]"]
  node_sitemap["Sitemap<br/>metadata route<br/>[sitemap.ts]"]
end

subgraph group_external["External Services"]
  node_github_api[("GitHub Users API<br/>public external API")]
  node_browser(("Browser platform<br/>runtime"))
end

node_layout -->|"hosts"| node_page
node_page -->|"renders"| node_experience
node_styles -->|"styles"| node_experience
node_experience -->|"composes"| node_ambient
node_experience -->|"renders"| node_card
node_experience -->|"fetches /api/github/:username"| node_github_route
node_github_route -->|"requests public user"| node_github_api
node_github_api -->|"profile or error"| node_github_route
node_github_types -->|"defines response fields"| node_github_route
node_github_types -->|"profile input"| node_driver_model
node_experience -->|"transforms profile"| node_driver_model
node_driver_model -->|"driver data"| node_card
node_experience -->|"initiates"| node_export
node_card -->|"render target"| node_export
node_export -->|"download and share APIs"| node_browser
node_og_image -.->|"link preview for"| node_page
node_twitter_image -.->|"social preview for"| node_page
node_sitemap -.->|"indexes"| node_page

click node_layout "https://github.com/blitzbugg/gitprix/blob/master/app/layout.tsx"
click node_page "https://github.com/blitzbugg/gitprix/blob/master/app/page.tsx"
click node_experience "https://github.com/blitzbugg/gitprix/blob/master/components/gitprix-experience.tsx"
click node_styles "https://github.com/blitzbugg/gitprix/blob/master/app/globals.css"
click node_ambient "https://github.com/blitzbugg/gitprix/blob/master/components/ambient-scene.tsx"
click node_card "https://github.com/blitzbugg/gitprix/blob/master/components/driver-card.tsx"
click node_export "https://github.com/blitzbugg/gitprix/blob/master/components/gitprix-experience.tsx"
click node_github_route "https://github.com/blitzbugg/gitprix/blob/master/app/api/github/%5Busername%5D/route.ts"
click node_github_types "https://github.com/blitzbugg/gitprix/blob/master/types/github.ts"
click node_driver_model "https://github.com/blitzbugg/gitprix/blob/master/lib/driver.ts"
click node_og_image "https://github.com/blitzbugg/gitprix/blob/master/app/opengraph-image.tsx"
click node_twitter_image "https://github.com/blitzbugg/gitprix/blob/master/app/twitter-image.tsx"
click node_sitemap "https://github.com/blitzbugg/gitprix/blob/master/app/sitemap.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_experience,node_styles,node_ambient,node_card,node_export toneBlue
class node_layout,node_page,node_github_route,node_github_types,node_driver_model,node_og_image,node_twitter_image,node_sitemap toneAmber
class node_github_api,node_browser toneMint
```

## Components

### Browser Experience

Single-page interactive driver-card experience.

- [GitPrix experience](https://github.com/blitzbugg/gitprix/blob/master/components/gitprix-experience.tsx): client orchestrator · Owns input, loading, error, success, export, and sharing states. · `components/gitprix-experience.tsx`
- [Global styling](https://github.com/blitzbugg/gitprix/blob/master/app/globals.css): CSS · Provides immersive race-scene and reduced-motion styling. · `app/globals.css`
- [Ambient scene](https://github.com/blitzbugg/gitprix/blob/master/components/ambient-scene.tsx): visual component · Renders circuit, stadium, and pit-wall atmosphere. · `components/ambient-scene.tsx`
- [Driver card](https://github.com/blitzbugg/gitprix/blob/master/components/driver-card.tsx): renderable component · Presents driver data and owns interactive tilt. · `components/driver-card.tsx`
- [PNG export and sharing](https://github.com/blitzbugg/gitprix/blob/master/components/gitprix-experience.tsx): browser capability · Rasterizes the rendered card for download, native sharing, X, and Reddit flows. · `components/gitprix-experience.tsx`

### Next.js Server

App routing, GitHub proxying, and metadata generation.

- [Root layout](https://github.com/blitzbugg/gitprix/blob/master/app/layout.tsx): Next.js layout · `app/layout.tsx`
- [Application page](https://github.com/blitzbugg/gitprix/blob/master/app/page.tsx): App Router page · `app/page.tsx`
- [Profile lookup route](https://github.com/blitzbugg/gitprix/blob/master/app/api/github/%5Busername%5D/route.ts): API route · Validates upstream results and shields presentation from GitHub API semantics. · `app/api/github/[username]/route.ts`
- [GitHub profile types](https://github.com/blitzbugg/gitprix/blob/master/types/github.ts): data contract · `types/github.ts`
- [Driver ratings](https://github.com/blitzbugg/gitprix/blob/master/lib/driver.ts): domain logic · Deterministically derives motorsport ratings from public profile signals and a stable username seed. · `lib/driver.ts`
- [Open Graph image](https://github.com/blitzbugg/gitprix/blob/master/app/opengraph-image.tsx): metadata route · `app/opengraph-image.tsx`
- [Twitter image](https://github.com/blitzbugg/gitprix/blob/master/app/twitter-image.tsx): metadata route · `app/twitter-image.tsx`
- [Sitemap](https://github.com/blitzbugg/gitprix/blob/master/app/sitemap.ts): metadata route · `app/sitemap.ts`

### External Services

- **GitHub Users API**: public external API · Unauthenticated public-profile source subject to rate limits.
- **Browser platform**: runtime · Provides fetch, rendered DOM, file download, and optional native sharing.

## Connections

- Root layout → Application page: hosts
- Application page → GitPrix experience: renders
- Global styling → GitPrix experience: styles
- GitPrix experience → Ambient scene: composes
- GitPrix experience → Driver card: renders
- GitPrix experience → Profile lookup route: fetches /api/github/:username
- Profile lookup route → GitHub Users API: requests public user
- GitHub Users API → Profile lookup route: profile or error
- GitHub profile types → Profile lookup route: defines response fields
- GitHub profile types → Driver ratings: profile input
- GitPrix experience → Driver ratings: transforms profile
- Driver ratings → Driver card: driver data
- GitPrix experience → PNG export and sharing: initiates
- Driver card → PNG export and sharing: render target
- PNG export and sharing → Browser platform: download and share APIs
- Open Graph image → Application page: link preview for
- Twitter image → Application page: social preview for
- Sitemap → Application page: indexes