# golang/example architecture

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

- Interactive diagram: https://gitdiagram.com/golang/example
- Repository: https://github.com/golang/example

## Overview

#### Repository Role

`golang.org/x/example` is a collection of independent Go examples, tutorials, and reference implementations rather than one deployable application. The root module (`go.mod`) supports shared examples, while several directories are standalone modules with their own `go.mod`.

#### Primary Entry Points

Runnable commands are distributed by example:
- CLI/library example: `hello/hello.go`, backed by `hello/reverse/reverse.go`.
- Basic HTTP server: `helloserver/server.go`.
- Stateful release-status HTTP service: `outyet/main.go`.
- App Engine starter application: `appengine-hello/app.go`, deployed through `appengine-hello/app.yaml`.
- Template-rendering server: `template/main.go`.
- Retrieval-augmented-generation server variants: `ragserver/ragserver/main.go`, `ragserver/ragserver-genkit/main.go`, and `ragserver/ragserver-langchaingo/main.go`.

#### Simple Command and Library Boundary

The `hello` example separates executable behavior from reusable string logic. `hello/hello.go` parses flags, logs, and prints output; `hello/reverse/reverse.go` supplies rune-safe string reversal. This is the repository’s basic command-to-library composition pattern.

#### HTTP Server Examples

Several self-contained services demonstrate Go’s `net/http` runtime:
- `helloserver/server.go` is the minimal HTTP-server entry point.
- `outyet/main.go` combines request handling with background state updates, synchronization, monitoring export, templates, and dependency injection.
- `template/main.go` renders page content using named template blocks from `template/index.tmpl` and `template/image.tmpl`.

These services own process startup and HTTP routing directly; they are examples, not a shared server framework.

#### Cloud Deployment Boundary

`appengine-hello/app.go` provides an App Engine-oriented HTTP application, with deployment/runtime settings declared separately in `appengine-hello/app.yaml`. Static browser assets reside under `appengine-hello/static/`, making this the principal browser-facing example and the only explicitly cloud-platform-configured application.

#### Go Type Analysis Tutorial

`gotypes/` is a tutorial suite around the standard `go/types` type checker. Individual command examples focus on distinct compiler-analysis stages: package inspection in `gotypes/pkginfo/main.go`, identifier definitions/uses in `gotypes/defsuses/main.go`, method/interface conformance in `gotypes/implements/main.go`, and typed expression results in `gotypes/typeandvalue/main.go`. `gotypes/gen.go` supports tutorial/example generation.

#### RAG Server Implementations

`ragserver/` contains parallel implementations of a document retrieval and generation service. The baseline server uses `ragserver/ragserver/main.go` plus vector-store integration in `ragserver/ragserver/weaviate.go`; alternative orchestration stacks live in `ragserver/ragserver-genkit/main.go` and `ragserver/ragserver-langchaingo/main.go`. JSON request/response handling is local to each implementation. Weaviate is the material external vector-database dependency, provisioned for integration workflows by `ragserver/tests/docker-compose.yml`.

#### Structured Logging Guide

`slog-handler-guide/` evolves custom `log/slog` Handler implementations across incremental versions. The final/concurrency-aware form is represented by `slog-handler-guide/indenthandler4/indent_handler.go`; earlier directories preserve pedagogical stages rather than serving as production dependencies.

Main entry points: [`ragserver/tests/docker-compose.yml`](https://github.com/golang/example/blob/master/ragserver/tests/docker-compose.yml) (Weaviate), [`appengine-hello/app.go`](https://github.com/golang/example/blob/master/appengine-hello/app.go) (App Engine app), [`gotypes/pkginfo/main.go`](https://github.com/golang/example/blob/master/gotypes/pkginfo/main.go) (package inspection), [`gotypes/defsuses/main.go`](https://github.com/golang/example/blob/master/gotypes/defsuses/main.go) (definitions and uses)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http_examples["HTTP examples"]
  node_hello_server["hello server<br/>HTTP command<br/>[server.go]"]
  node_outyet_service["outyet service<br/>stateful HTTP service<br/>[main.go]"]
  node_template_server["template server<br/>HTTP command<br/>[main.go]"]
  node_page_templates["page templates<br/>template files<br/>[index.tmpl]"]
  node_appengine_app["App Engine app<br/>cloud HTTP app<br/>[app.go]"]
  node_appengine_config["App Engine config<br/>deployment manifest<br/>[app.yaml]"]
  node_appengine_static["static assets<br/>browser assets"]
end

subgraph group_type_tutorial["go/types tutorial"]
  node_pkginfo["package inspection<br/>tutorial command<br/>[main.go]"]
  node_defsuses["definitions and uses<br/>tutorial command<br/>[main.go]"]
  node_implements["method conformance<br/>tutorial command<br/>[main.go]"]
  node_typeandvalue["type and value<br/>tutorial command<br/>[main.go]"]
  node_gotypes_generator["tutorial generator<br/>Go generator<br/>[gen.go]"]
end

subgraph group_rag["RAG servers"]
  node_rag_baseline["baseline RAG server<br/>RAG HTTP server<br/>[main.go]"]
  node_weaviate_adapter["Weaviate integration<br/>vector-store adapter<br/>[weaviate.go]"]
  node_weaviate[("Weaviate<br/>external vector database<br/>[docker-compose.yml]")]
  node_genkit_rag["Genkit RAG server<br/>RAG HTTP server<br/>[main.go]"]
  node_langchaingo_rag["LangChainGo RAG server<br/>RAG HTTP server<br/>[main.go]"]
end

node_hello_cmd["hello command<br/>Go CLI<br/>[hello.go]"]
node_reverse_lib["reverse library<br/>Go package<br/>[reverse.go]"]
node_slog_handler["IndentHandler v4<br/>slog Handler example<br/>[indent_handler.go]"]

node_hello_cmd -->|"uses"| node_reverse_lib
node_template_server -->|"renders"| node_page_templates
node_appengine_config -->|"deploys"| node_appengine_app
node_appengine_app -->|"serves"| node_appengine_static
node_pkginfo -.->|"tutorial suite"| node_defsuses
node_defsuses -.->|"tutorial suite"| node_implements
node_implements -.->|"tutorial suite"| node_typeandvalue
node_gotypes_generator -.->|"generates examples"| node_pkginfo
node_rag_baseline -->|"retrieves via"| node_weaviate_adapter
node_weaviate_adapter -->|"queries"| node_weaviate
node_genkit_rag -.->|"retrieval backend"| node_weaviate
node_langchaingo_rag -.->|"retrieval backend"| node_weaviate

click node_hello_cmd "https://github.com/golang/example/blob/master/hello/hello.go"
click node_reverse_lib "https://github.com/golang/example/blob/master/hello/reverse/reverse.go"
click node_hello_server "https://github.com/golang/example/blob/master/helloserver/server.go"
click node_outyet_service "https://github.com/golang/example/blob/master/outyet/main.go"
click node_template_server "https://github.com/golang/example/blob/master/template/main.go"
click node_page_templates "https://github.com/golang/example/blob/master/template/index.tmpl"
click node_appengine_app "https://github.com/golang/example/blob/master/appengine-hello/app.go"
click node_appengine_config "https://github.com/golang/example/blob/master/appengine-hello/app.yaml"
click node_pkginfo "https://github.com/golang/example/blob/master/gotypes/pkginfo/main.go"
click node_defsuses "https://github.com/golang/example/blob/master/gotypes/defsuses/main.go"
click node_implements "https://github.com/golang/example/blob/master/gotypes/implements/main.go"
click node_typeandvalue "https://github.com/golang/example/blob/master/gotypes/typeandvalue/main.go"
click node_gotypes_generator "https://github.com/golang/example/blob/master/gotypes/gen.go"
click node_slog_handler "https://github.com/golang/example/blob/master/slog-handler-guide/indenthandler4/indent_handler.go"
click node_rag_baseline "https://github.com/golang/example/blob/master/ragserver/ragserver/main.go"
click node_weaviate_adapter "https://github.com/golang/example/blob/master/ragserver/ragserver/weaviate.go"
click node_weaviate "https://github.com/golang/example/blob/master/ragserver/tests/docker-compose.yml"
click node_genkit_rag "https://github.com/golang/example/blob/master/ragserver/ragserver-genkit/main.go"
click node_langchaingo_rag "https://github.com/golang/example/blob/master/ragserver/ragserver-langchaingo/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_hello_server,node_outyet_service,node_template_server,node_page_templates,node_appengine_app,node_appengine_config,node_appengine_static toneBlue
class node_pkginfo,node_defsuses,node_implements,node_typeandvalue,node_gotypes_generator toneAmber
class node_rag_baseline,node_weaviate_adapter,node_weaviate,node_genkit_rag,node_langchaingo_rag toneMint
class node_hello_cmd,node_reverse_lib,node_slog_handler toneNeutral
```

## Components

### HTTP examples

Independent net/http services.

- [hello server](https://github.com/golang/example/blob/master/helloserver/server.go): HTTP command · `helloserver/server.go`
- [outyet service](https://github.com/golang/example/blob/master/outyet/main.go): stateful HTTP service · Routes, state updates, synchronization, templates, and metrics. · `outyet/main.go`
- [template server](https://github.com/golang/example/blob/master/template/main.go): HTTP command · `template/main.go`
- [page templates](https://github.com/golang/example/blob/master/template/index.tmpl): template files · Named blocks for rendered pages. · `template/index.tmpl`
- [App Engine app](https://github.com/golang/example/blob/master/appengine-hello/app.go): cloud HTTP app · Browser-facing Go application. · `appengine-hello/app.go`
- [App Engine config](https://github.com/golang/example/blob/master/appengine-hello/app.yaml): deployment manifest · `appengine-hello/app.yaml`
- **static assets**: browser assets

### go/types tutorial

Commands illustrating type-checker analysis stages.

- [package inspection](https://github.com/golang/example/blob/master/gotypes/pkginfo/main.go): tutorial command · `gotypes/pkginfo/main.go`
- [definitions and uses](https://github.com/golang/example/blob/master/gotypes/defsuses/main.go): tutorial command · `gotypes/defsuses/main.go`
- [method conformance](https://github.com/golang/example/blob/master/gotypes/implements/main.go): tutorial command · `gotypes/implements/main.go`
- [type and value](https://github.com/golang/example/blob/master/gotypes/typeandvalue/main.go): tutorial command · `gotypes/typeandvalue/main.go`
- [tutorial generator](https://github.com/golang/example/blob/master/gotypes/gen.go): Go generator · `gotypes/gen.go`

### RAG servers

Parallel retrieval-and-generation implementations.

- [baseline RAG server](https://github.com/golang/example/blob/master/ragserver/ragserver/main.go): RAG HTTP server · Local JSON request and response handling. · `ragserver/ragserver/main.go`
- [Weaviate integration](https://github.com/golang/example/blob/master/ragserver/ragserver/weaviate.go): vector-store adapter · `ragserver/ragserver/weaviate.go`
- [Weaviate](https://github.com/golang/example/blob/master/ragserver/tests/docker-compose.yml): external vector database · Provisioned for integration workflows. · `ragserver/tests/docker-compose.yml`
- [Genkit RAG server](https://github.com/golang/example/blob/master/ragserver/ragserver-genkit/main.go): RAG HTTP server · Alternative orchestration stack. · `ragserver/ragserver-genkit/main.go`
- [LangChainGo RAG server](https://github.com/golang/example/blob/master/ragserver/ragserver-langchaingo/main.go): RAG HTTP server · Alternative orchestration stack. · `ragserver/ragserver-langchaingo/main.go`

### Other components

- [hello command](https://github.com/golang/example/blob/master/hello/hello.go): Go CLI · `hello/hello.go`
- [reverse library](https://github.com/golang/example/blob/master/hello/reverse/reverse.go): Go package · Rune-safe string reversal. · `hello/reverse/reverse.go`
- [IndentHandler v4](https://github.com/golang/example/blob/master/slog-handler-guide/indenthandler4/indent_handler.go): slog Handler example · Final concurrency-aware pedagogical implementation. · `slog-handler-guide/indenthandler4/indent_handler.go`

## Connections

- hello command → reverse library: uses
- template server → page templates: renders
- App Engine config → App Engine app: deploys
- App Engine app → static assets: serves
- package inspection → definitions and uses: tutorial suite
- definitions and uses → method conformance: tutorial suite
- method conformance → type and value: tutorial suite
- tutorial generator → package inspection: generates examples
- baseline RAG server → Weaviate integration: retrieves via
- Weaviate integration → Weaviate: queries
- Genkit RAG server → Weaviate: retrieval backend
- LangChainGo RAG server → Weaviate: retrieval backend
