Glossary

English（this file） · 日本語

A quick reference to karasu’s core vocabulary. karasu is inspired by the C4 Model but has its own terms, separating a system’s logical, physical, and organizational structure.

This page is an index, not the source of truth: each entry gives a one-line definition and links to the authoritative document (Core Concepts, Syntax, Style, Tags & annotations, Diagnostics). When a definition here and its source disagree, the source wins — follow the link.

Related TPLs: TPL-1296 — this glossary re-presents definitions that live canonically elsewhere; entries must not contradict their linked source.

Core concepts

Three-dimensional structure — karasu describes architecture across three independent dimensions — logical (what / why), physical (how), and organizational (who) — written in separate files but navigated together. Concepts
Logical structure — the what / why view: the access path (who reaches which services through what) and the service hierarchy (the business functionality each service contains). Concepts
Physical structure — the how view: the deployment units that actually run the logical services, written in .krs files separate from the logical model. Concepts
Organizational structure — the who view: which team owns which service or domain, making ownership explicit alongside the architecture. Concepts
Drill-down — the way to understand a model: start from a bounded overview and descend into any node that has children for more detail. Concepts
Scoped glance — the cognitive principle behind drill-down: show a bounded field of view at a time rather than one diagram of everything. Concepts
Ghost — a semi-transparent placeholder for a node outside the current viewpoint that still participates in a dependency, so boundaries stay visible as the field narrows. Concepts
Text as the source of truth — the .krs text (not a diagram or binary file) is the authoritative model; every input path converges on it. Concepts

Logical element kinds

System — a boundary containing owned services, external services, clients, and the users that reach them. Concepts
Service — an independent unit of business capability; the middle tier of both the access path and the service hierarchy. Concepts
Domain — a business-concern boundary inside a service, close to DDD’s Bounded Context; the level at which cross-service dependencies are reasoned about. Concepts
Usecase — a business operation or task within a domain; the level at which CRUD operations on resources are declared. Concepts
Resource — what a usecase operates on: a table, an external API, a file, and so on. Concepts
User — an actor that drives the system, tagged [human] or [ai]. Syntax
Client — software the project itself ships to act on a user’s behalf (mobile / web / desktop / CLI / device / extension / embed), distinct from third-party browsers or agents. Concepts
Form-factor tag — one of seven recognized tags on a client ([mobile], [web], [desktop], [cli], [device], [extension], [embed]) classifying the surface a user reaches the system through. Syntax
Infra — a data store shared by services, declared at system level: database (of tables), queue (of messages), or storage (of buckets). Services depend on infra, never the reverse. Syntax

Relationships

Edge — a directed relationship between logical nodes: -> for synchronous, --> for asynchronous communication / dependency. Concepts
Explicit / implicit edge — explicit edges are written by hand; implicit edges are synthesized at service level when domain-level edges cross a service boundary (tagged [implicit]). Concepts
Aggregation — collapsing multiple domain-level edges between the same service pair into one implicit edge per sync / async kind on the system view. Concepts
realizes — a relationship pointing from a physical deployment unit (concrete) to the logical service / domain / client / infra node (abstract) it implements. Concepts
owns — a relationship, declared inside a team, stating that the team owns a service, domain, or other logical node. Concepts
handles — a property on a client or service declaring which domain ids it exposes to its callers; validated against the one-hop expose rule. Syntax
delivers — a relationship from a service to the client(s) it ships (the BFF / SSR pattern); ownership-and-shipping, not a build pipeline. Syntax

Physical / deploy vocabulary

Deployment unit — a physical form that realizes a logical node. Kinds: war, jar, oci, lambda, function, assets, job (one-shot, or recurring with a schedule), and artifact (catch-all). Syntax
store — a dedicated deployment kind for a managed data store (Aurora, SQS, S3, …) that realizes a logical infra node; carries type and realizes, but no runtime or schedule. Syntax

Organizational vocabulary

Organization — the root of an organizational hierarchy; contains nested teams. Syntax
Team — a group with responsibility that may own services / domains and contain members; may be nested under a parent team. Syntax
Member — an individual belonging to a team, with optional contact properties (slack, github, …). Syntax
Role — a short description of what a user does in the system; an actor archetype, not an authorization primitive (no RBAC). Syntax
Ownership inheritance — the rule that a node with no owns of its own belongs to the team owning its nearest owned ancestor. Syntax
Team dependency — a derived relation between two teams: one team owns a node that depends on a node the other owns. Nothing declares it in .krs; it is the join of owns against the logical edges, kept separate per sync / async and marked nested when one team is the other’s ancestor. Read it with karasu team-dependencies. Not a synonym for communication, which is bound to node-to-node edges above.
Structural overlap — a derived fact about containment rather than about calls: a node one team owns living inside a node another team owns. Both ends must declare owns themselves — an inherited owner is by definition the enclosing node’s team, so inheritance never reads as an overlap. No edge crosses that boundary, so a team dependency cannot express it, yet the two teams still have to agree on the enclosing structure. Reported alongside team dependencies, in its own channel. Only the teams that actually cross are named — a team owning on both sides is part of no breach — and the overlap is marked nested only when every crossing/enclosing team pairing sits in one team’s subtree in the org tree; a single foreign owner makes the whole overlap cross-team.

Related TPLs: TPL-2635 — 所有を読む側は宣言だけを読むのか nearest owned ancestor まで遡るのかを宣言する。TPL-2161 — 宣言された多重所属（共同所有）を派生 index で捨てない。

Tags & annotations

Tag — a [name] declaration expressing architectural position or role (e.g. [external]), to which styles respond. Tags & annotations
Annotation — an @name declaration expressing lifecycle / development state, inherited by child nodes unless overridden. Tags & annotations
Tags vs. annotations — tags describe what a node is (position / role); annotations describe where it is in its lifecycle. Tags & annotations
[external] — a tag for nodes outside the system boundary; rendered with a dashed border and gray tone. Tags & annotations
System-assigned tags — tags karasu adds automatically to edges: [implicit], [cyclic], and [read] / [write] (from a usecase’s CRUD operations). Tags & annotations
Lifecycle annotations — @deprecated, @new, @experimental, and @migration_target; some accept parameters (until, from). Tags & annotations
Annotation inheritance — a parent’s annotation flows to its children until a child carries its own, keeping lifecycle context across drill-down. Concepts
Capability — a device or browser permission a client requests (open-set identifiers); distinct from a resource, which is storage. Tags & annotations

CRUD

Operations — the CRUD verbs (create / read / update / delete) a usecase performs on a resource. Syntax
Verb decoration — verb:crud syntax mapping a domain verb to CRUD intent (e.g. list:read, enqueue:create), so authors keep their own vocabulary while still feeding the CRUD matrix. Syntax
CRUD matrix — a usecase × resource read/write matrix derived from declared operations (rendered as a view, or via karasu matrix). Syntax

Style

.krs.style — a stylesheet that maps selectors to visual properties, cascading like CSS over the model. Style
Selector — a CSS-like pattern targeting nodes or edges by kind, tag, annotation, id, or a compound of these. Style
Specificity — the score deciding which rule wins when several selectors match the same node (kind = 1 … id = 100). Style
Layout hints — escape-hatch properties (column, direction, label-position, label-offset) nudging layout without the engine enforcing them. Style
Legend — a top-level block mapping colors to meanings, rendered as a footer band; entries are a swatch (literal hex) or a ref (resolved through the style cascade). Syntax

Diagnostics

Rule — a statement of what the language allows or forbids (e.g. “an edge originates within its enclosing block”). Diagnostics
Diagnostic — a named report that a rule was violated, identified by a diagnostic code (e.g. edge-source-mismatch). Diagnostics
Diagnostic code — the stable, never-renamed string id of a diagnostic, consumed by the LSP, app, and tooling. Diagnostics
Severity — a diagnostic’s level: error (model malformed, construct rejected), warning (a real defect to fix), or info (a fact, not a defect). Diagnostics
Warn-don’t-error — an unresolved reference is reported as a warning and the source node is kept, so structural facts survive a dangling link. Diagnostics
Domain dispersal — the same domain id appearing under multiple services in one system; surfaced as info, not an error. Concepts
Cyclic dependency — a cycle of sync (->) edges; detected statically, tagged [cyclic], and rendered in red. Async edges are excluded as intentional loose coupling. Concepts

Multi-file

Import — bringing another .krs file’s content into the current one: named (import { Foo } from "p.krs"), whole-file (import "p.krs"), or directory (import "dir/"). Syntax
System reopen — the same system id appearing in more than one file is merged into a single block (closer-to-root properties win on conflict) rather than treated as a duplicate. Syntax

Project & process vocabulary

These terms are about how the karasu project is run, not the modeling language. They are useful when contributing; their sources live in the repository (not on this site).

Design Doc — a detailed “how to build it” exploration (constraints, alternatives, approach) kept in docs/design/ while a decision is open. Once decided it is promoted to an ADR and the Design Doc is deleted. process.md
ADR (Architecture Decision Record) — a concise record of a settled design decision (adopted or rejected) — the “why we decided this”, kept in docs/adr/. docs/adr/
TPL (Test Perspective Library) — a structured, reusable record of a recurring failure pattern to verify against, kept in docs/test-perspectives/. Each entry is proactive (predicted from a principle / non-goal) or retrospective (generalized from a past bug). Where an ADR records a past decision, a TPL prompts future verification. docs/test-perspectives/
Acceptance Test (AT) — an acceptance-criteria record for a change, kept in docs/acceptance/, marking which criteria are automated vs. verified by hand. process.md
Roadmap — the living document of karasu’s overall direction and Syntax v1.0 readiness, kept in docs/roadmap.md. roadmap.md