Foreword

Archlang is a language for describing system architecture as text. You write .arch files; every diagram, view, dependency graph, and impact report is derived from them. There is no separate drawing tool to keep in sync, no second source of truth to drift, no whiteboard photograph that everyone forgets to update.

If you have used UML tools, RSM, Sparx EA, or a corner of Confluence holding outdated PowerPoint slides, you already know the problem this book is about. Pictures of architecture rot. Source files don’t.

Who this book is for

Three audiences:

Engineers and architects modeling a system they own or work in. You will read chapters 1 through 13 and probably stop there.
Platform teams that want to define their own kinds (a payment_service, a relational_db) on top of the stdlib. You will continue through chapter 19.
Tool builders integrating Archlang into editors, dashboards, or pipelines. The appendices at the end of the book (Grammar, Keywords, Stdlib Kinds, Cheatsheet) are for you; the chapters give the mental model behind them.

This book assumes you have written code before. It does not assume you have used an ADL (architecture description language) — most haven’t.

The three ideas

Most of Archlang follows directly from three commitments. Each one is unusual enough to deserve naming up front.

1. Architecture is defined, not drawn. A diagram is a projection of the model, the way a chart is a projection of a spreadsheet. You never edit the diagram to change the system; you edit the source. The diagram catches up on the next render.

2. Types are form templates, not classes. When you declare type module service { required cascade team }, you are not building a class hierarchy. You are defining what every service instance in your workspace must fill in. An instance is the filled-in form. Chapters 14–18 unpack this.

3. Change is first-class. Architecture has a history. Branches are future states; commits are decisions; diffs are architecture deltas. Stable IDs anchor identity through renames so a refactor never looks like “everything was deleted and added.” Chapter 14 is where this lands.

If any of those sound wrong on first read, that’s expected. Each one has a chapter that earns it.

What this book is not

Not a tutorial on diagramming tools. Archlang produces diagrams; it isn’t driven by them.
Not a CMDB. It records what your architecture is, not what is currently running.
Not a runtime. It doesn’t execute processes; it describes them.
Not a programming language. There are no functions, no values beyond identifiers and strings, no per-field type system. The expressive power lives in the metamodel.

How to read

Chapters are numbered and meant to be read in order, at least the first time. Each one introduces concepts the next one builds on. Mindset chapters (14, 17) are longer than the others — they earn their length.

If you only consume kinds defined by the stdlib or your platform team, you can stop at the end of Chapter 14 and come back to Part IV when you need to define your own kind.

The appendices at the end (Grammar, Keywords, Stdlib Kinds, Cheatsheet) are separate. They’re for lookup once you already know what you’re looking for.

What’s next

Chapter 1: Setup → — get a workspace running.