Landscape
A landscape is one view of the architecture, generated from a model rather than drawn. Eight of them are planned; each answers a question the others cannot.
The eight views
Section titled “The eight views”| Landscape | Question | Rendered from | Status |
|---|---|---|---|
| DDD | What is the domain, and where are its seams? | ba-hub (external) | open the DDD landscape |
| C4 | How is the software structured, at four zoom levels? | arch-c4 |
open the C4 landscape |
| Events | What crosses the boundaries between contexts? | arch-eventcatalog |
open the event catalog |
| API | What is exposed, under what contract? | api-hub (external) | open the API portal |
| Components | What is deployed, and how does a use case flow through it? | arch-appmap |
planned |
| Databases | What is stored, and how is it related? | not yet assigned | planned |
| Processes | What does the business actually do? | not yet assigned | planned |
| AI | Where do models and agents sit? | not yet assigned | planned |
DDD, C4, Events and API are rendered today. The rest are placeholders — and Components is the only one whose module already exists; Databases, Processes and AI have none assigned at all.
DDD is rendered outside this repo, by ba-hub’s ba-ddd-mapper. It used to
be an arch-ddd module here, built on ContextMapper; that module was removed
and the landscape moved rather than being dropped. It still produces both halves
of the view — the strategic context map and the tactical aggregate diagrams —
from one source, so DDD and API are now external in the same way.
A planned landscape links to its own teaser page under /landscape/<name>,
not to this document. It states the question that view answers, what it will put
on screen and where it currently stands. Sending that click here instead
answered a question nobody had asked.
Components is the runtime view: a catalogue of what is deployed, and for
each component the inner flow of a main use case as it actually ran. That is
what arch-appmap records from real executions, which is why AI no longer
claims it — “where do the models and agents sit” is not a question a call trace
answers.
Databases covers SQL and NoSQL alike. Relational stores get the entity–relationship treatment — tables, columns, keys, foreign keys — while document, key-value, graph and wide-column stores are described on their own terms rather than bent into tables. For the schemaless ones the shape has to be inferred from the data, because there is rarely a declaration to read.
The C4 landscape
Section titled “The C4 landscape”arch-c4 holds the model as LikeC4 source and builds it
into a static site, so the context, container and component views are all
generated from one model and cannot contradict each other. Adding a model is a
folder under arch-c4/src; past the first, the site grows a project switcher.
The link above is deliberately not the site’s address. /doc/* is
prerendered at build time, so an address written here would be frozen into the
image and ARCH_C4_URL would silently stop mattering. /go/c4 is a
server-rendered redirect that reads the variable per request instead — the
address is configuration, and configuration does not belong in prose.
ARCH_C4_URL defaults to http://arch-c4.localhost, the ingress host
arch-c4’s values-local.yaml enables on a local cluster.
Why API links out
Section titled “Why API links out”The API landscape is not reimplemented here. api-hub already owns it
end to end: contracts are parsed, validated, scored and registered there, and
its portal renders the catalogue and the reference view. A second view over the
same registry would be a staler copy of a page that already works, so the panel
links out instead.
The address comes from API_PORTAL_URL, defaulting to
http://api-portal.localhost — the ingress host api-hub’s values-local.yaml
enables on a local cluster. Point it elsewhere per environment.
Adding a landscape
Section titled “Adding a landscape”A view earns a panel when something renders it. Until then it stays planned:
a panel that links to an empty page is worse than a panel that admits it is not
built. Flip the status in src/pages/landscape/index.astro when the module
behind it ships.
If the new landscape lives at an address a chart configures, add a reader to
src/lib/links.ts and — when a prerendered page needs to link to it — a
redirect beside src/pages/go/c4.ts. A prerendered page must never call the
reader directly.