Component Diagram

flowchart TB
  gw["HTTP Gateway<br/><i>inbound</i>"]
  subgraph svc["Order API — inside the container"]
    direction TB
    ctrl["Order Controller<br/><i>validation, mapping</i>"]
    app["Order Application Service<br/><i>use cases, transactions</i>"]
    dom["Order Domain Model<br/><i>invariants, state rules</i>"]
    repo["Order Repository<br/><i>persistence port</i>"]
    pay["Payment Client<br/><i>anti-corruption adapter</i>"]
    out["Outbox Publisher"]
  end
  db[("PostgreSQL")]
  ext["Payment Provider"]
  bus[["Kafka"]]

  gw --> ctrl --> app
  app --> dom
  app --> repo --> db
  app --> pay --> ext
  app --> out --> db
  out -.->|"relay reads outbox"| bus

What it is

C4 level three: one container opened up. The boxes are cohesive groupings of code — not classes, and not every package — chosen because each has a responsibility you could state in a sentence. It is the last level worth drawing by hand; below this, the code is the diagram.

When you produce it

Only for the containers that are genuinely hard. A component view of a CRUD service is make-work. A component view of the one service holding the domain logic everybody argues about earns its keep, especially when onboarding.

Who reads it

Engineers joining the codebase, and reviewers checking that the dependency direction actually points the way the team claims it does.

What good looks like

• Dependency arrows point inwards towards the domain, and the diagram makes that visible rather than asserting it in prose.
• Adapters to the outside world are named as adapters.
• Each box's responsibility is on the diagram in three or four words.
• It is generated or checked by an architecture fitness test where possible, so it cannot silently drift from the code.

Common mistakes

• Drawing every class. That is a UML class diagram and nobody will read it.
• Drawing it for every service. Three good component diagrams beat forty stale ones.
• Hiding the direction of dependency, which is the one thing this level is uniquely able to show.