# talkgo/night architecture

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

- Interactive diagram: https://gitdiagram.com/talkgo/night
- Repository: https://github.com/talkgo/night

## Overview

##### Project Type and Purpose
- This is a Hugo-based static website (“Go 夜读”) with embedded Go tools and GitHub Actions.
- The repository holds:
- A Hugo site (content/, layouts/, static/, themes/hugo-material-docs/)
- Go code (talkgo.go, custom actions under actions/)
- CI/CD definitions (.github/workflows/, netlify/, Makefile)
- Purpose: maintain and publish the Go 夜读 blog, generate monthly/weekly digests and link checks, deploy to Netlify.

##### Main Components
A. Developer
- Local machine, clones repo, writes Markdown content, Go code, modifies config.
B. Version Control & CI Platform
- GitHub Repository
- GitHub Workflows:
· links.yml (link validation)
· monthly.yml (monthly digest via custom Go action)
· weekly-digest.yml
- Custom Go Actions (actions/monthly.go, issuesinfo.json)
C. Static Site Generator
- Hugo engine uses config.toml, archetypes/, content/, layouts/, static/, themes/
- talkgo.go (CLI helper for generating docs or feeding Hugo)
D. Hosting & Deployment
- Netlify (reads netlify/state.json, builds via Hugo, publishes to CDN)
- Optional: GitHub Pages fallback
E. Clients & External Services
- Web browsers access the static site via Netlify CDN
- External integrations (YouTube, Twitter, Slack badges)

##### Relationships & Data Flow
1. Developer → GitHub: push commits (content, code, config).
2. GitHub → CI (Workflows): on push or schedule triggers link check, weekly/monthly generation.
3. CI → Go Actions: actions/monthly.go reads issuesinfo.json, GitHub API to assemble digests.
4. CI → Hugo build: Hugo reads content/layouts/theme → static HTML/CSS/JS.
5. CI → Netlify deploy: Netlify build hook receives site files, publishes to CDN.
6. Client browsers → Netlify CDN: retrieve static assets.

##### Architectural Patterns & Design Principles
- Static Site Generator (SSG) pattern: decouple content (Markdown) from presentation (Hugo theme).
- Event-driven CI: GitHub Actions trigger on commits or scheduled events.
- Infrastructure as Code: Netlify config, GitHub workflow YAMLs, Makefile.
- Extendibility via Go-based custom actions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Environment"
        Dev(("Developer Workstation\nMarkdown & Go code")):::dev
        MF["Makefile"]:::dev
    end

    subgraph "Version Control & CI"
        GitRepo[(GitHub Repo)]:::ci
        LinkCheck["Link Validation\nlinks.yml"]:::ci
        Weekly["Weekly Digest\nweekly-digest.yml"]:::ci
        Monthly["Monthly Digest\nmonthly.yml"]:::ci
        GoAction["Custom Go Action\nmonthly.go"]:::ci
        GoMod["actions/go.mod"]:::ci
        Issues["issuesinfo.json"]:::ci
    end

    subgraph "Static Site Generation"
        HugoBuild["Hugo Build\nvia talkgo CLI & Hugo"]:::ssg
        Site[(Static Site Files)]:::ssg
        subgraph "Hugo Sources"
            Config["config.toml"]:::ssg
            Arche["archetypes/"]:::ssg
            Content["content/"]:::ssg
            Layouts["layouts/"]:::ssg
            StaticDir["static/"]:::ssg
            Themes["themes/hugo-material-docs/"]:::ssg
        end
        Talkgo["talkgo.go"]:::ssg
        TalkgoTest["talkgo_test.go"]:::ssg
    end

    subgraph "Hosting & Deployment"
        NetlifyBuild["Netlify Build & Deploy"]:::hosting
        NetState[".netlify/state.json"]:::hosting
        NetDir["netlify/"]:::hosting
        CDN["Netlify CDN"]:::hosting
    end

    subgraph "Clients & External"
        Browser["Web Browser"]:::client
    end

    subgraph "External Integration"
        YT["YouTube"]:::external
        TW["Twitter"]:::external
        SL["Slack Badges"]:::external
    end

    Dev -->|push commits| GitRepo
    Dev --> MF
    MF --> GitRepo

    GitRepo -->|on push/schedule| LinkCheck
    GitRepo -->|on schedule| Weekly
    GitRepo -->|on schedule| Monthly

    Monthly --> GoAction
    GoAction --> GoMod
    GoAction --> Issues

    LinkCheck --> HugoBuild
    Weekly --> HugoBuild
    Monthly --> HugoBuild

    Config --> HugoBuild
    Arche --> HugoBuild
    Content --> HugoBuild
    Layouts --> HugoBuild
    StaticDir --> HugoBuild
    Themes --> HugoBuild
    Talkgo --> HugoBuild
    TalkgoTest --> HugoBuild

    HugoBuild --> Site
    Site --> NetlifyBuild
    NetState --> NetlifyBuild
    NetDir --> NetlifyBuild
    NetlifyBuild --> CDN
    CDN --> Browser

    Browser -->|embeds| YT
    Browser -->|embeds| TW
    Browser -->|embeds| SL

    click Config "https://github.com/talkgo/night/blob/master/config.toml"
    click Arche "https://github.com/talkgo/night/tree/master/archetypes/"
    click Content "https://github.com/talkgo/night/tree/master/content/"
    click Layouts "https://github.com/talkgo/night/tree/master/layouts/"
    click StaticDir "https://github.com/talkgo/night/tree/master/static/"
    click Themes "https://github.com/talkgo/night/tree/master/themes/hugo-material-docs/"
    click Talkgo "https://github.com/talkgo/night/blob/master/talkgo.go"
    click TalkgoTest "https://github.com/talkgo/night/blob/master/talkgo_test.go"
    click LinkCheck "https://github.com/talkgo/night/blob/master/.github/workflows/links.yml"
    click Monthly "https://github.com/talkgo/night/blob/master/.github/workflows/monthly.yml"
    click Weekly "https://github.com/talkgo/night/blob/master/.github/weekly-digest.yml"
    click GoAction "https://github.com/talkgo/night/blob/master/actions/monthly.go"
    click GoMod "https://github.com/talkgo/night/blob/master/actions/go.mod"
    click Issues "https://github.com/talkgo/night/blob/master/actions/issuesinfo.json"
    click NetState "https://github.com/talkgo/night/blob/master/.netlify/state.json"
    click NetDir "https://github.com/talkgo/night/tree/master/netlify/"
    click MF "https://github.com/talkgo/night/tree/master/Makefile"

    classDef dev fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef ci fill:#a2c8f5,stroke:#333,stroke-width:1px
    classDef ssg fill:#f5c38a,stroke:#333,stroke-width:1px
    classDef hosting fill:#d6a8f5,stroke:#333,stroke-width:1px
    classDef client fill:#cfcfcf,stroke:#333,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
```
