# avelino/awesome-go architecture

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

- Interactive diagram: https://gitdiagram.com/avelino/awesome-go
- Repository: https://github.com/avelino/awesome-go

## Overview

Awesome Go is a curated directory of Go projects, with a Go program that turns the list into a static website. The visible workflow converts the source Markdown, extracts categories and links, builds project pages, rewrites index links, and produces a sitemap and copied assets. The code also fetches and caches GitHub/GitLab project metadata. Several implementation details fall in omitted portions of main.go, so the graph limits connections to relationships visible in the excerpts or explicitly documented by the README.

Main entry points: [`main.go`](https://github.com/avelino/awesome-go/blob/main/main.go) (Site builder), [`pkg/markdown/convert.go`](https://github.com/avelino/awesome-go/blob/main/pkg/markdown/convert.go) (Markdown converter), [`pkg/slug/generator.go`](https://github.com/avelino/awesome-go/blob/main/pkg/slug/generator.go) (Slug generator), [`tmpl`](https://github.com/avelino/awesome-go/tree/main/tmpl) (HTML templates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Site generation"]
  node_builder["Site builder<br/>[main.go]"]
end

subgraph group_content["Content processing"]
  node_markdown["Markdown converter<br/>[convert.go]"]
  node_slug["Slug generator<br/>[generator.go]"]
  node_categories["Category extraction<br/>[main.go]"]
  node_projects["Project pages<br/>[main.go]"]
end

subgraph group_metadata["Project metadata"]
  node_metadatafetch["Metadata fetching<br/>[main.go]"]
  node_cache["Metadata cache<br/>[main.go]"]
end

subgraph group_presentation["Site presentation"]
  node_index["Index rendering<br/>[main.go]"]
  node_linkrewrite["Index link rewrite<br/>[main.go]"]
  node_categoryrender["Category rendering<br/>[main.go]"]
  node_sitemap["Sitemap rendering<br/>[main.go]"]
  node_templates["HTML templates"]
  node_assets["Static assets"]
end

node_maintainer(("List maintainer"))
node_github["GitHub API"]
node_gitlab["GitLab API"]
node_output["Generated site"]

node_maintainer -->|"updates list"| node_builder
node_builder -->|"renders index"| node_index
node_index -->|"converts Markdown"| node_markdown
node_markdown -->|"generates IDs"| node_slug
node_builder -->|"extracts categories"| node_categories
node_categories -->|"creates slugs"| node_slug
node_builder -->|"builds pages"| node_projects
node_builder -.->|"fetches metadata"| node_metadatafetch
node_metadatafetch -->|"requests metadata"| node_github
node_metadatafetch -->|"requests metadata"| node_gitlab
node_metadatafetch -->|"reads and writes"| node_cache
node_builder -->|"rewrites links"| node_linkrewrite
node_builder -->|"renders categories"| node_categoryrender
node_categoryrender -->|"executes template"| node_templates
node_builder -->|"renders sitemap"| node_sitemap
node_sitemap -->|"executes template"| node_templates
node_builder -->|"copies assets"| node_assets
node_builder -->|"writes site"| node_output

click node_builder "https://github.com/avelino/awesome-go/blob/main/main.go"
click node_markdown "https://github.com/avelino/awesome-go/blob/main/pkg/markdown/convert.go"
click node_slug "https://github.com/avelino/awesome-go/blob/main/pkg/slug/generator.go"
click node_categories "https://github.com/avelino/awesome-go/blob/main/main.go"
click node_projects "https://github.com/avelino/awesome-go/blob/main/main.go"
click node_index "https://github.com/avelino/awesome-go/blob/main/main.go"
click node_linkrewrite "https://github.com/avelino/awesome-go/blob/main/main.go"
click node_categoryrender "https://github.com/avelino/awesome-go/blob/main/main.go"
click node_sitemap "https://github.com/avelino/awesome-go/blob/main/main.go"
click node_templates "https://github.com/avelino/awesome-go/tree/main/tmpl"
click node_assets "https://github.com/avelino/awesome-go/tree/main/tmpl/assets"
click node_metadatafetch "https://github.com/avelino/awesome-go/blob/main/main.go"
click node_cache "https://github.com/avelino/awesome-go/blob/main/main.go"

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_builder toneBlue
class node_markdown,node_slug,node_categories,node_projects toneAmber
class node_metadatafetch,node_cache,node_github,node_gitlab toneMint
class node_index,node_linkrewrite,node_categoryrender,node_sitemap,node_templates,node_assets toneRose
class node_maintainer,node_output toneIndigo
```

## Components

### Site generation

- [Site builder](https://github.com/avelino/awesome-go/blob/main/main.go): `main.go`

### Content processing

- [Markdown converter](https://github.com/avelino/awesome-go/blob/main/pkg/markdown/convert.go): `pkg/markdown/convert.go`
- [Slug generator](https://github.com/avelino/awesome-go/blob/main/pkg/slug/generator.go): `pkg/slug/generator.go`
- [Category extraction](https://github.com/avelino/awesome-go/blob/main/main.go): `main.go`
- [Project pages](https://github.com/avelino/awesome-go/blob/main/main.go): `main.go`

### Project metadata

- [Metadata fetching](https://github.com/avelino/awesome-go/blob/main/main.go): `main.go`
- [Metadata cache](https://github.com/avelino/awesome-go/blob/main/main.go): `main.go`

### Site presentation

- [Index rendering](https://github.com/avelino/awesome-go/blob/main/main.go): `main.go`
- [Index link rewrite](https://github.com/avelino/awesome-go/blob/main/main.go): `main.go`
- [Category rendering](https://github.com/avelino/awesome-go/blob/main/main.go): `main.go`
- [Sitemap rendering](https://github.com/avelino/awesome-go/blob/main/main.go): `main.go`
- [HTML templates](https://github.com/avelino/awesome-go/tree/main/tmpl): `tmpl`
- [Static assets](https://github.com/avelino/awesome-go/tree/main/tmpl/assets): `tmpl/assets`

### Other components

- **List maintainer**
- **GitHub API**
- **GitLab API**
- **Generated site**

## Connections

- List maintainer → Site builder: updates list (evidence: `README.md`)
- Site builder → Index rendering: renders index (evidence: `main.go`)
- Index rendering → Markdown converter: converts Markdown (evidence: `main.go`)
- Markdown converter → Slug generator: generates IDs (evidence: `pkg/markdown/convert.go`)
- Site builder → Category extraction: extracts categories (evidence: `main.go`)
- Category extraction → Slug generator: creates slugs (evidence: `main.go`)
- Site builder → Project pages: builds pages (evidence: `main.go`)
- Site builder → Metadata fetching: fetches metadata (evidence: `main.go`)
- Metadata fetching → GitHub API: requests metadata (evidence: `main.go`)
- Metadata fetching → GitLab API: requests metadata (evidence: `main.go`)
- Metadata fetching → Metadata cache: reads and writes (evidence: `main.go`)
- Site builder → Index link rewrite: rewrites links (evidence: `main.go`)
- Site builder → Category rendering: renders categories (evidence: `main.go`)
- Category rendering → HTML templates: executes template (evidence: `main.go`)
- Site builder → Sitemap rendering: renders sitemap (evidence: `main.go`)
- Sitemap rendering → HTML templates: executes template (evidence: `main.go`)
- Site builder → Static assets: copies assets (evidence: `main.go`)
- Site builder → Generated site: writes site (evidence: `main.go`)
