# brgjr10/gitphoto architecture

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

## Overview

gitphoto is a self-hosted GitHub repository cover generator. A README author or web-UI user submits a repository reference; the HTTP server streams progress or returns a cover while the pipeline fetches metadata, checks the cache, clones the repository, selects a preview, renders a 1280×640 PNG, and stores it. Preview selection covers README images, static sites, optional dev servers, source snippets, and empty fallbacks; composition adds repository identity, statistics, language styling, and a themed backdrop. The graph follows documented and excerpted calls; some preview-selection internals are represented from README capabilities because their implementation was not excerpted.

Main entry points: [`src/services/pipeline.js`](https://github.com/brgjr10/gitphoto/blob/master/src/services/pipeline.js) (Cover pipeline), [`src/services/renderer.js`](https://github.com/brgjr10/gitphoto/blob/master/src/services/renderer.js) (Browser renderer), [`src/render/banner.js`](https://github.com/brgjr10/gitphoto/blob/master/src/render/banner.js) (Banner composition), [`src/server.js`](https://github.com/brgjr10/gitphoto/blob/master/src/server.js) (HTTP and SSE)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Request handling"]
  node_server["HTTP and SSE<br/>[server.js]"]
  node_web_ui["Web UI<br/>[app.js]"]
end

subgraph group_workflow["Repository workflow"]
  node_pipeline["Cover pipeline<br/>[pipeline.js]"]
  node_metadata["Repository metadata<br/>[github.js]"]
  node_workspace["Clone workspace<br/>[workspace.js]"]
  node_preview_detection["Preview ranking<br/>[detect.js]"]
  node_dependency_install["Dependency installation<br/>[install.js]"]
  node_preview_servers["Preview servers<br/>[preview.js]"]
  node_renderer["Browser renderer<br/>[renderer.js]"]
end

subgraph group_rendering["Cover rendering"]
  node_banner["Banner composition<br/>[banner.js]"]
  node_styles["Theme styles<br/>[styles.js]"]
  node_icons["Icons and highlighting<br/>[icons.js]"]
  node_format["Text formatting<br/>[format.js]"]
end

subgraph group_support["Runtime support"]
  node_cover_cache[("Cover cache<br/>[cover-cache.js]")]
  node_cover_files[("Cover files<br/>[pipeline.js]")]
  node_config["Runtime configuration<br/>[config.js]"]
  node_semaphore["Render concurrency<br/>[semaphore.js]"]
  node_markdown["README snippet<br/>[markdown.js]"]
  node_image_size["Image dimensions<br/>[image-size.js]"]
  node_page_wait["Image load wait<br/>[page-wait.js]"]
end

node_author(("README author"))
node_ui_user(("Web UI user"))
node_github["GitHub API"]

node_author -->|"requests PNG"| node_server
node_ui_user -->|"uses"| node_web_ui
node_web_ui -->|"streams progress"| node_server
node_server -->|"generates cover"| node_pipeline
node_pipeline -->|"fetches metadata"| node_metadata
node_metadata -->|"queries API"| node_github
node_pipeline -->|"checks cache"| node_cover_cache
node_pipeline -->|"clones repository"| node_workspace
node_pipeline -->|"limits concurrency"| node_semaphore
node_pipeline -->|"renders preview"| node_renderer
node_pipeline -->|"writes PNG"| node_cover_files
node_pipeline -->|"builds snippet"| node_markdown
node_renderer -->|"ranks strategies"| node_preview_detection
node_renderer -->|"enables dev strategy"| node_dependency_install
node_renderer -->|"captures site"| node_preview_servers
node_preview_servers -->|"launches processes"| node_workspace
node_preview_detection -->|"probes dimensions"| node_image_size
node_renderer -->|"sizes images"| node_image_size
node_renderer -->|"waits for images"| node_page_wait
node_renderer -->|"builds document"| node_banner
node_banner -->|"applies styles"| node_styles
node_banner -->|"renders icons"| node_icons
node_banner -->|"formats content"| node_format
node_pipeline -->|"uses paths and settings"| node_config
node_renderer -->|"uses render settings"| node_config

click node_server "https://github.com/brgjr10/gitphoto/blob/master/src/server.js"
click node_web_ui "https://github.com/brgjr10/gitphoto/blob/master/public/app.js"
click node_pipeline "https://github.com/brgjr10/gitphoto/blob/master/src/services/pipeline.js"
click node_metadata "https://github.com/brgjr10/gitphoto/blob/master/src/services/github.js"
click node_workspace "https://github.com/brgjr10/gitphoto/blob/master/src/services/workspace.js"
click node_preview_detection "https://github.com/brgjr10/gitphoto/blob/master/src/services/detect.js"
click node_dependency_install "https://github.com/brgjr10/gitphoto/blob/master/src/services/install.js"
click node_preview_servers "https://github.com/brgjr10/gitphoto/blob/master/src/services/preview.js"
click node_renderer "https://github.com/brgjr10/gitphoto/blob/master/src/services/renderer.js"
click node_cover_cache "https://github.com/brgjr10/gitphoto/blob/master/src/lib/cover-cache.js"
click node_cover_files "https://github.com/brgjr10/gitphoto/blob/master/src/services/pipeline.js"
click node_config "https://github.com/brgjr10/gitphoto/blob/master/src/config.js"
click node_semaphore "https://github.com/brgjr10/gitphoto/blob/master/src/lib/semaphore.js"
click node_markdown "https://github.com/brgjr10/gitphoto/blob/master/src/lib/markdown.js"
click node_banner "https://github.com/brgjr10/gitphoto/blob/master/src/render/banner.js"
click node_styles "https://github.com/brgjr10/gitphoto/blob/master/src/render/styles.js"
click node_icons "https://github.com/brgjr10/gitphoto/blob/master/src/render/icons.js"
click node_format "https://github.com/brgjr10/gitphoto/blob/master/src/render/format.js"
click node_image_size "https://github.com/brgjr10/gitphoto/blob/master/src/lib/image-size.js"
click node_page_wait "https://github.com/brgjr10/gitphoto/blob/master/src/lib/page-wait.js"

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_server,node_web_ui,node_ui_user toneBlue
class node_pipeline,node_metadata,node_workspace,node_preview_detection,node_dependency_install,node_preview_servers,node_renderer toneAmber
class node_banner,node_styles,node_icons,node_format,node_github toneMint
class node_cover_cache,node_cover_files,node_config,node_semaphore,node_markdown,node_image_size,node_page_wait toneRose
class node_author toneIndigo
```

## Components

### Request handling

- [HTTP and SSE](https://github.com/brgjr10/gitphoto/blob/master/src/server.js): `src/server.js`
- [Web UI](https://github.com/brgjr10/gitphoto/blob/master/public/app.js): `public/app.js`

### Repository workflow

- [Cover pipeline](https://github.com/brgjr10/gitphoto/blob/master/src/services/pipeline.js): `src/services/pipeline.js`
- [Repository metadata](https://github.com/brgjr10/gitphoto/blob/master/src/services/github.js): `src/services/github.js`
- [Clone workspace](https://github.com/brgjr10/gitphoto/blob/master/src/services/workspace.js): `src/services/workspace.js`
- [Preview ranking](https://github.com/brgjr10/gitphoto/blob/master/src/services/detect.js): `src/services/detect.js`
- [Dependency installation](https://github.com/brgjr10/gitphoto/blob/master/src/services/install.js): `src/services/install.js`
- [Preview servers](https://github.com/brgjr10/gitphoto/blob/master/src/services/preview.js): `src/services/preview.js`
- [Browser renderer](https://github.com/brgjr10/gitphoto/blob/master/src/services/renderer.js): `src/services/renderer.js`

### Cover rendering

- [Banner composition](https://github.com/brgjr10/gitphoto/blob/master/src/render/banner.js): `src/render/banner.js`
- [Theme styles](https://github.com/brgjr10/gitphoto/blob/master/src/render/styles.js): `src/render/styles.js`
- [Icons and highlighting](https://github.com/brgjr10/gitphoto/blob/master/src/render/icons.js): `src/render/icons.js`
- [Text formatting](https://github.com/brgjr10/gitphoto/blob/master/src/render/format.js): `src/render/format.js`

### Runtime support

- [Cover cache](https://github.com/brgjr10/gitphoto/blob/master/src/lib/cover-cache.js): `src/lib/cover-cache.js`
- [Cover files](https://github.com/brgjr10/gitphoto/blob/master/src/services/pipeline.js): `src/services/pipeline.js`
- [Runtime configuration](https://github.com/brgjr10/gitphoto/blob/master/src/config.js): `src/config.js`
- [Render concurrency](https://github.com/brgjr10/gitphoto/blob/master/src/lib/semaphore.js): `src/lib/semaphore.js`
- [README snippet](https://github.com/brgjr10/gitphoto/blob/master/src/lib/markdown.js): `src/lib/markdown.js`
- [Image dimensions](https://github.com/brgjr10/gitphoto/blob/master/src/lib/image-size.js): `src/lib/image-size.js`
- [Image load wait](https://github.com/brgjr10/gitphoto/blob/master/src/lib/page-wait.js): `src/lib/page-wait.js`

### Other components

- **README author**
- **Web UI user**
- **GitHub API**

## Connections

- README author → HTTP and SSE: requests PNG (evidence: `README.md`)
- Web UI user → Web UI: uses (evidence: `README.md`)
- Web UI → HTTP and SSE: streams progress (evidence: `README.md`)
- HTTP and SSE → Cover pipeline: generates cover (evidence: `src/server.js`)
- Cover pipeline → Repository metadata: fetches metadata (evidence: `src/services/pipeline.js`)
- Repository metadata → GitHub API: queries API (evidence: `README.md`)
- Cover pipeline → Cover cache: checks cache (evidence: `src/services/pipeline.js`)
- Cover pipeline → Clone workspace: clones repository (evidence: `src/services/pipeline.js`)
- Cover pipeline → Render concurrency: limits concurrency (evidence: `src/services/pipeline.js`)
- Cover pipeline → Browser renderer: renders preview (evidence: `src/services/pipeline.js`)
- Cover pipeline → Cover files: writes PNG (evidence: `src/services/pipeline.js`)
- Cover pipeline → README snippet: builds snippet (evidence: `README.md`)
- Browser renderer → Preview ranking: ranks strategies (evidence: `src/services/renderer.js`)
- Browser renderer → Dependency installation: enables dev strategy (evidence: `README.md`)
- Browser renderer → Preview servers: captures site (evidence: `src/services/renderer.js`)
- Preview servers → Clone workspace: launches processes (evidence: `src/services/preview.js`)
- Preview ranking → Image dimensions: probes dimensions (evidence: `src/services/detect.js`)
- Browser renderer → Image dimensions: sizes images (evidence: `src/services/renderer.js`)
- Browser renderer → Image load wait: waits for images (evidence: `src/services/renderer.js`)
- Browser renderer → Banner composition: builds document (evidence: `src/services/renderer.js`)
- Banner composition → Theme styles: applies styles (evidence: `src/render/banner.js`)
- Banner composition → Icons and highlighting: renders icons (evidence: `src/render/banner.js`)
- Banner composition → Text formatting: formats content (evidence: `src/render/banner.js`)
- Cover pipeline → Runtime configuration: uses paths and settings (evidence: `src/services/pipeline.js`)
- Browser renderer → Runtime configuration: uses render settings (evidence: `src/services/renderer.js`)