# beejjorgensen/bgnet architecture

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

- Interactive diagram: https://gitdiagram.com/beejjorgensen/bgnet
- Repository: https://github.com/beejjorgensen/bgnet

## Overview

This repository is not an application runtime; it is the source and publishing pipeline for Beej’s Guide to Network Programming. The main “product” is documentation, with a secondary subsystem of standalone C networking examples.

1. **Content authoring layer**
   - The core guide text lives in `src/` as chapter-sized Markdown files named `bgnet_part_*.md`.
   - `src/README.md`, `src/cover/`, and the PDF files in `src/` support the book output, including cover and formatted artifacts.
   - This is the primary source-of-truth for the guide content.

2. **Example code layer**
   - Runnable C examples are in `source/examples/`.
   - These are small, isolated programs demonstrating networking concepts such as clients, servers, polling, select, broadcast, address conversion, and packing/endianness.
   - They are not a single application; they are independent teaching samples used to illustrate the prose.

3. **Build orchestration layer**
   - The top-level `Makefile` coordinates full-site and full-release builds.
   - `src/Makefile` and `source/Makefile` handle local builds for their respective content trees.
   - The build is document-centric: it assembles text, generated PDFs, example outputs, and website assets into distributable form.

4. **External build dependency**
   - The repo depends on an external sibling project, `bgbspd`, described as Beej’s Guide Build System for Pandoc.
   - That build system is an important architectural boundary: the repo provides content, while `bgbspd` provides the Pandoc/LaTeX packaging logic.

5. **Document generation toolchain**
   - The build requires `make`, Python 3, Pandoc, XeLaTeX, and Liberation fonts.
   - This indicates a pipeline that converts Markdown into publication formats, especially PDF, with font-sensitive rendering handled through LaTeX.

6. **Published outputs**
   - The repo contains already-built artifacts such as `src/cs.pdf`, `src/dataencap.pdf`, and translated PDFs in `translations/`.
   - These outputs are the deliverables of the build pipeline, separate from the editable source files.

7. **Website publishing layer**
   - `website/` holds static web assets: `index.html`, `index.css`, errata, and related pages.
   - This is a static publication surface, not a dynamic web service.
   - The build’s `stage` step copies the generated guide and website content into a deployable directory.

8. **Translation subsystem**
   - `translations/` contains localized deliverables and translator-specific assets, including Portuguese HTML/PDF and a Russian A4 PDF.
   - This suggests the source repository supports downstream localization without mixing translation logic into the core guide source.

9. **Release and staging flow**
   - The documented release path is: edit source in `src/` and `source/examples/` → build with `make all` → stage with `make stage` → publish staged outputs and website.
   - The top-level `upload` target is the release handoff point, using a configurable `UPLOADDIR`.

10. **Containerized build path**
   - `Dockerfile` packages the build environment so the entire publication pipeline can run reproducibly without local tool installation.
   - The container mounts the repo and runs the same build sequence, producing a ready-to-publish `stage/` directory.

11. **Overall architecture boundary**
   - There is no networked backend or service tier here.
   - The only executable code is the sample C programs; everything else is content, build automation, and static publishing.
   - For an architecture diagram, this repo is best modeled as a documentation production system with three outputs: PDFs, static website pages, and translated artifacts.

Main entry points: [`Makefile`](https://github.com/beejjorgensen/bgnet/tree/main/Makefile) (Top makefile), [`src/cs.pdf`](https://github.com/beejjorgensen/bgnet/blob/main/src/cs.pdf) (Guide PDFs), [`source/examples/Makefile`](https://github.com/beejjorgensen/bgnet/tree/main/source/examples/Makefile) (Example build), [`src/Makefile`](https://github.com/beejjorgensen/bgnet/tree/main/src/Makefile) (Source makefile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Content authoring"]
  node_src_parts["Guide chapters<br/>markdown source"]
  node_src_support["Book assets<br/>book support<br/>[README.md]"]
  node_guide_flow(("Guide source<br/>content pipeline"))
end

subgraph group_examples["Example code"]
  node_examples_programs["C examples<br/>sample programs<br/>[client.c]"]
  node_examples_build["Example build<br/>example makefile"]
end

subgraph group_build["Build orchestration"]
  node_top_make["Top makefile<br/>release orchestrator"]
  node_src_make["Source makefile<br/>content build"]
  node_source_make["Source tree build<br/>content build"]
  node_bgbspd{{"BGBSPD<br/>external build system"}}
  node_dockerfile["Docker build<br/>container build"]
  node_release_flow(("Release flow<br/>publishing pipeline"))
end

subgraph group_publish["Published outputs"]
  node_pdfs["Guide PDFs<br/>generated pdfs<br/>[cs.pdf]"]
  node_staging[("Stage dir<br/>release staging")]
end

subgraph group_web["Website publishing"]
  node_website_assets["Website assets<br/>static site<br/>[index.html]"]
end

subgraph group_locales["Translations"]
  node_translations_out["Translated outputs<br/>localized artifacts<br/>[bgnet_ptbr.html]"]
end

node_src_parts -->|"authors"| node_guide_flow
node_src_support -->|"supports"| node_guide_flow
node_examples_programs -->|"built by"| node_examples_build
node_examples_build -->|"coordinated by"| node_source_make
node_guide_flow -->|"built by"| node_src_make
node_src_make -->|"driven by"| node_top_make
node_source_make -->|"driven by"| node_top_make
node_top_make -->|"delegates to"| node_bgbspd
node_bgbspd -->|"renders"| node_pdfs
node_top_make -->|"produces"| node_pdfs
node_top_make -->|"assembles"| node_staging
node_dockerfile -->|"runs"| node_top_make
node_pdfs -->|"copied into"| node_staging
node_website_assets -->|"copied into"| node_staging
node_translations_out -->|"published via"| node_staging
node_release_flow -->|"orchestrates"| node_top_make
node_release_flow -->|"hands off"| node_staging

click node_src_parts "https://github.com/beejjorgensen/bgnet/blob/main/src/bgnet_part_0100_intro.md"
click node_src_support "https://github.com/beejjorgensen/bgnet/blob/main/src/README.md"
click node_examples_programs "https://github.com/beejjorgensen/bgnet/blob/main/source/examples/client.c"
click node_examples_build "https://github.com/beejjorgensen/bgnet/tree/main/source/examples/Makefile"
click node_top_make "https://github.com/beejjorgensen/bgnet/tree/main/Makefile"
click node_src_make "https://github.com/beejjorgensen/bgnet/tree/main/src/Makefile"
click node_source_make "https://github.com/beejjorgensen/bgnet/tree/main/source/Makefile"
click node_dockerfile "https://github.com/beejjorgensen/bgnet/tree/main/Dockerfile"
click node_pdfs "https://github.com/beejjorgensen/bgnet/blob/main/src/cs.pdf"
click node_website_assets "https://github.com/beejjorgensen/bgnet/blob/main/website/index.html"
click node_translations_out "https://github.com/beejjorgensen/bgnet/blob/main/translations/bgnet_ptbr.html"

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_src_parts,node_src_support,node_guide_flow toneBlue
class node_examples_programs,node_examples_build toneAmber
class node_top_make,node_src_make,node_source_make,node_bgbspd,node_dockerfile,node_release_flow toneMint
class node_pdfs,node_staging toneRose
class node_website_assets toneIndigo
class node_translations_out toneTeal
```

## Components

### Content authoring

Primary guide source files and book-support material.

- [Guide chapters](https://github.com/beejjorgensen/bgnet/blob/main/src/bgnet_part_0100_intro.md): markdown source · Chapter-sized Markdown files that form the main guide text. · `src/bgnet_part_0100_intro.md`
- [Book assets](https://github.com/beejjorgensen/bgnet/blob/main/src/README.md): book support · Supporting source material such as README and cover assets for the book build. · `src/README.md`
- **Guide source**: content pipeline · Main editorial flow from source chapters and support material into publishable guide artifacts.

### Example code

Standalone C networking samples used in the guide.

- [C examples](https://github.com/beejjorgensen/bgnet/blob/main/source/examples/client.c): sample programs · Independent runnable networking examples demonstrating concepts from the prose. · `source/examples/client.c`
- [Example build](https://github.com/beejjorgensen/bgnet/tree/main/source/examples/Makefile): example makefile · Local build entrypoint for compiling and organizing the example programs. · `source/examples/Makefile`

### Build orchestration

Make-based publication and packaging pipeline.

- [Top makefile](https://github.com/beejjorgensen/bgnet/tree/main/Makefile): release orchestrator · Coordinates full-site and full-release builds across the repository. · `Makefile`
- [Source makefile](https://github.com/beejjorgensen/bgnet/tree/main/src/Makefile): content build · Build rules for the guide source tree and document outputs. · `src/Makefile`
- [Source tree build](https://github.com/beejjorgensen/bgnet/tree/main/source/Makefile): content build · Build rules for the example/code source tree. · `source/Makefile`
- **BGBSPD**: external build system · External sibling build system providing Pandoc/LaTeX packaging logic.
- [Docker build](https://github.com/beejjorgensen/bgnet/tree/main/Dockerfile): container build · Containerized environment for reproducible documentation builds. · `Dockerfile`
- **Release flow**: publishing pipeline · Build, stage, and upload path that turns source into distributable outputs.

### Published outputs

Generated PDFs and staged deliverables.

- [Guide PDFs](https://github.com/beejjorgensen/bgnet/blob/main/src/cs.pdf): generated pdfs · Built book artifacts such as cs.pdf and dataencap.pdf. · `src/cs.pdf`
- **Stage dir**: release staging · Deployable staging area assembled before upload.

### Website publishing

Static site assets for online publication.

- [Website assets](https://github.com/beejjorgensen/bgnet/blob/main/website/index.html): static site · Static publishing surface with pages, styles, and errata. · `website/index.html`

### Translations

Localized deliverables and translation-specific assets.

- [Translated outputs](https://github.com/beejjorgensen/bgnet/blob/main/translations/bgnet_ptbr.html): localized artifacts · Localized HTML/PDF deliverables for Portuguese and Russian variants. · `translations/bgnet_ptbr.html`

## Connections

- Guide chapters → Guide source: authors · Chapter Markdown is the core editorial input.
- Book assets → Guide source: supports · Supplementary source files contribute to the book output.
- C examples → Example build: built by · Example programs are compiled and organized by the example makefile.
- Example build → Source tree build: coordinated by · The examples subtree is managed through its local build rules.
- Guide source → Source makefile: built by · Guide content is turned into formatted outputs by the source-tree build.
- Source makefile → Top makefile: driven by · Top-level build invokes the source content build.
- Source tree build → Top makefile: driven by · Top-level build invokes the examples/content subtree build.
- Top makefile → BGBSPD: delegates to · Packaging and Pandoc/LaTeX logic comes from the external build system.
- BGBSPD → Guide PDFs: renders · External packaging logic produces book PDFs.
- Top makefile → Guide PDFs: produces · Full builds generate the distributable guide PDFs.
- Top makefile → Stage dir: assembles · Release builds gather outputs into a staging directory.
- Docker build → Top makefile: runs · Containerized builds execute the same make-based pipeline.
- Guide PDFs → Stage dir: copied into · Generated PDFs are staged for release.
- Website assets → Stage dir: copied into · Static website pages are included in the staged release.
- Translated outputs → Stage dir: published via · Localized deliverables are part of the staged publish set.
- Release flow → Top makefile: orchestrates · Release flow is coordinated through the top-level make targets.
- Release flow → Stage dir: hands off · The staged directory is the release handoff point.
