archgen

archgen is a small Go utility that generates a set of Markdown documents from special comments in Go code. Documentation is grouped by services that are explicitly mentioned in comments.

Comments are parsed only when a block starts with one of the following lines:

• // archgen: service
• // archgen: function
• // archgen: handler
• // archgen: restriction
• // archgen: integration

Additionally, when the --c4-notation flag is enabled, the following C4‑notation related blocks are also collected:

• // archgen: context
• // archgen: containers
• // archgen: components
• // archgen: code

All consecutive // comment lines immediately following this header are merged into a single text block and written to Markdown documents grouped per service.

For each service ServiceName discovered in comments a separate directory <out>/ServiceName/ is generated with files:

• service → ServiceName/service.md
• function → ServiceName/function.md
• handler → ServiceName/handler.md
• restriction → ServiceName/restriction.md
• integration → ServiceName/integration.md

When --c4-notation is passed the following additional files are generated:

• context → ServiceName/context.md
• containers → ServiceName/containers.md
• components → ServiceName/components.md
• code → ServiceName/code.md

If the type is not from this list or the first line does not match // archgen: <kind>, the block is ignored.

Example comments in Go code (base/)

// archgen: service AuthService
// Сервис аутентификации пользователей.
// Отвечает за регистрацию, логин, логаут,
// управление refresh‑токенами и проверку прав доступа.

// archgen: function RegisterUser
// Регистрирует нового пользователя по email и паролю.

// archgen: handler POST /api/v1/login
// Аутентифицирует пользователя и возвращает его идентификатор.

// archgen: restriction
// Ограничивает число попыток логина до 5 в минуту на пару (ip, email).

// archgen: integration Postgres
// Использует таблицы users и sessions для хранения учетных записей и сессий.

These blocks are collected into service.md, function.md, handler.md, restriction.md, integration.md in the specified output directory.

Example comments in Go code (c4/)

// archgen: context PaymentSystem
// High-level context of the payment system.
// Shows main users and external systems.

// archgen: containers PaymentSystem
// WebApp - handles HTTP requests from users.
// API - public API for partners.
// Database - stores payments and invoices.

// archgen: components WebApp
// HTTP layer, controllers, validation, views.

// archgen: code PaymentRepository
// Implementation details of payment persistence.

When --c4-notation is enabled these blocks are collected into context.md, containers.md, components.md, code.md.

Each generated file starts with a marker for IDEs and tools:

<!-- Code generated by archgen; DO NOT EDIT. -->

Usage

Build:

go build -o archgen .

Run with output directory:

./archgen --out docs/arch

or equivalently:

./archgen --output docs/arch

With additional C4‑notation documents:

./archgen --out docs/arch --c4-notation

Specify input directory with Go sources (base/ example) (by default the current working directory is used):

./archgen --in ./examples --out docs/arch
# or equivalently:
./archgen --input ./examples --out docs/arch

Specify input directory with Go sources (c4/ example):

./archgen --in ./examples/c4 --out docs/arch-c4 --c4-notation

Where:

• --in — main flag for the input directory with Go sources;
• --input — alias for --in;
• --out / --output — directory where Markdown files are generated;
• --c4-notation — additionally generates C4‑notation Markdown files (context.md, containers.md, components.md, code.md) for all services discovered in comments.

What happens on run

On each run the tool:

• recursively walks the current directory or the directory passed via --in / --input;
• looks for .go files (skipping .git, .idea, vendor);
• collects comment blocks starting with // archgen: <kind>;
• recreates the output directory (--out / --output) from scratch: any previously generated documentation is deleted;
• groups comments by service and kind and writes Markdown files into per‑service directories.

Structure of generated files

Each Markdown file has the following structure:

• file header marker: <!-- Code generated by archgen; DO NOT EDIT. -->;
• top‑level heading with the type name (Service, Function, …);
• multiple level‑2 sections (## Service 1, ## Service 2, …);
• under each block a source location line (_Source: path/to/file.go:LINE_);
• then the text collected from comments.

Linking entities together

To make the documentation more interconnected it is recommended to introduce stable identifiers and refer to them explicitly:

• Service names: in service comments use the first word as a stable service ID, e.g. AuthService, BillingService.

Every block (function, handler, restriction, integration, C4) is automatically associated with the last service block declared above it in the same Go file, so дополнительных служебных строк вида Service: AuthService писать не требуется.