likec4

The Problem

Architecture diagrams are typically hand‑crafted and quickly become stale as code evolves. Likec4 automates this by letting you describe a C4‑style model in a domain‑specific language and then generating live, always‑up‑to‑date diagrams from the source code itself.

What This Does

Likec4 is not a single monolith but a portfolio of six self‑contained projects (see the directory breakdown). The packages layer (6702 files, 6458 code files) houses the core modeling logic:

• packages/core/src/model/DeploymentElementModel.ts – defines style, name, shape, color, icon and is called from 28 other files.
• packages/core/src/model/LikeC4Model.ts – exposes fromParsed, create, fromDump, constructor, getOrCreateFolder; 16 callers reference it.
• packages/core/src/utils/invariant.ts – exports invariant, nonNullable, nonexhaustive; invariant itself is invoked from 80 call sites, making it a central consistency guard.

The apps layer (243 files) provides a playground and documentation UI; apps/playground/src/examples/ contains demo models (bigbank, rank, deployment, dynamic) that illustrate the language. Dockerfile at the root builds a container image, and package.json files use pnpm as the package manager. The repo also includes e2e tests, styled‑system utilities, and a .agents skill set for agent orchestration.

How It Is Wired

Execution starts from a handful of entry points identified by the call‑graph analysis:

Tracing the shortest paths shows two concrete side‑effects:

• init → write → filesystem via fs.writeFileSync (creates/overwrites generated diagram files).
• run → loadPrepackGitignore → filesystem via fs.readFile (reads the gitignore prepacked for the container).

The internal call graph also highlights high‑impact hubs: invariant (80 callers), includes (38), nonNullable (36), and isString (31). Changing any of these ripples through many modules, so they should be treated as stability anchors.

How To Use It

1. Install – pnpm install (the root package.json and all apps/*/package.json files use pnpm).
2. Build / run – The CLI is exposed via npx likec4 start (as documented in the README). This launches the development server that watches source files and refreshes diagrams automatically.
3. Configuration – No environment variables are required for basic operation; the model is defined in .likec4 DSL files placed alongside your code. The Dockerfile (Dockerfile) builds a container image (node:22.22.3-bookworm / -slim) that can be deployed if you prefer an isolated runtime.
4. Custom notation – Override or extend element types in packages/core/src/model/ or add new shapes via the skill add-new-element-shape under .agents/skills/.

Missing evidence – The repo does not expose a pyproject.toml or Makefile; all build‑time steps are covered by the Node‑based tooling and Docker.

Real‑World Use

A development team wanting to keep their C4 diagrams in sync can add a .likec4 model describing containers, components, and relations. Running npx likec4 start starts a Vite dev server (configured in apps/playground/vite.config.ts) that parses the model, invokes packages/core/src/compute-view/ to compute views, and streams the resulting SVG/PNG to the browser. When a service class is renamed or a new API endpoint is added, the diagram updates on the next refresh, eliminating the “drift” problem entirely.

Code Health & Issues

The static analysis produced seven hygiene findings (ranked by severity/confidence):

• [CRITICAL] Keep secrets out of workflows a fork can trigger – .github/workflows/prepare-release.yaml contains BOT_APP_PRIVATE_KEY, BOT_APP_ID. A PR could exfiltrate these publish tokens. Fix: move secret‑using steps into a workflow_run job that never checks out PR code, or gate on an environment with required reviewers.
• [HIGH] Pin third‑party GitHub Actions to a commit SHA – pnpm/action-setup@v6, cloudflare/wrangler-action@v4, docker/setup-docker-action@v4, docker/login-action@v3 use mutable version tags. Fix: replace each @vN with the 40‑character commit SHA and let Dependabot bump the SHAs.
• [MEDIUM] Pin the container base image by digest – Dockerfile uses node:22.22.3-bookworm and node:22.22.3-bookworm-slim without a digest. Fix: use node:22.22.3-bookworm@sha256:<digest> and enable Dependabot’s docker ecosystem.
• [MEDIUM] Gate pull requests on a dependency vulnerability scan – CI has no dependency‑scan step. Fix: add dependency-review-action on pull_request or run osv-scanner on push and a schedule.
• [MEDIUM] Set persist-credentials: false on checkout – checkout keeps the token, allowing later steps to read pushable credentials. Fix: add with: persist-credentials: false and pass an explicit token only to the push step.
• [MEDIUM] Add a non‑root USER to the image – Dockerfile has no USER directive; the process runs as root. Fix: create an unprivileged user, chown needed paths, and end the Dockerfile with USER.
• [LOW] Set timeout-minutes on workflow jobs – docker.yaml declares no job timeout, risking overlapping runs on a two‑hourly schedule. Fix: add a realistic timeout-minutes to each job.

The Bottom Line

Likec4 delivers a pragmatic way to keep architecture diagrams live and code‑driven, with a clear modeling language and a modest set of entry points that make the system easy to understand and extend. The codebase is well‑structured (6 self‑contained projects) and has CI, Docker, and test coverage in place. However, several SDLC hygiene items—especially secrets in workflows, mutable action versions, and an untagged Docker base image—need attention before the project can be considered production‑ready at scale. Teams that value up‑to‑date visual architecture and are willing to address the listed security/configuration gaps will find Likec4 a valuable addition to their tooling stack.