20a-overall-architecture

Level: beginner · Reading time: 3 min · Prerequisite: book/chapters/20a-architecture-globale.html · Track: essential · Maturity: reviewed · Last review: 2026-05-09

Prerequisites: book/chapters/20a-architecture-globale.html. See also: book/chapters/20a-architecture-globale.html, book/chapters/27-grammar.html, book/chapters/31-build-errors.html.

Concrete Problem

Compiler-facing chapters become vague when they talk about stages but never show how data crosses stage boundaries.

Red Thread (Single Project)

One small compiler-like flow reads a source input, validates shape, transforms state, and produces an exit-oriented result.

For what

This chapter helps the reader build a mental model of pipeline boundaries.

What you are going to do

You will inspect a staged flow, name what each stage owns, then compare it to a collapsed design that hides those boundaries.

Coherent example

space demo/compiler

pick ParseState {
  case Parsed(nodes: int)
  case Failed(code: int)
}

proc parse(size: int) -> ParseState {
  if size <= 0 { give ParseState.Failed(11) }
  give ParseState.Parsed(size)
}

proc lower(state: ParseState) -> int {
  match state {
    case Parsed(nodes) { give nodes }
    case Failed(code) { give code }
    otherwise { give 70 }
  }
}

Global explanation

Pipeline chapters are most useful when they keep stage ownership explicit. The reader should know what the parse stage owns, what the transform stage owns, and where errors cross boundaries.

Invalid case

proc broken_pipeline(size: int) -> int {
  match size
    case 0 { give 0 }
  }
}

This invalid case is intentionally small. It exists to isolate the contract failure that the chapter is trying to teach.

Common pitfalls

• Describing a pipeline as a list of names with no data movement.
• Collapsing stages so tightly that diagnostics lose their context.
• Teaching advanced compiler topics without a small staged example.

Short exercise

Add one extra stage to the example and explain what data it receives and what it returns.

Summary in 5 points

1. Stages are ownership boundaries.
2. Data movement matters as much as stage names.
3. Small compiler examples should still show multiple layers.
4. Broken stage structure should remain visible in invalid examples.
5. A mental model is a data-flow model.