Open source

A practical first look at the open-source tld project

A useful first contribution starts with understanding the shape of the project, reproducing the behavior you want to improve, and keeping the change small enough to review.

It is easy to approach an architecture diagramming tool as if it were only a canvas. The open-source tld project is broader: its repository contains a Go application, a React-based web interface, command-line workflows, documentation, and build assets that are bundled together. That combination lets the project support both interactive diagramming and structured automation, while also making it worth understanding where a change belongs before editing.

This guide is a grounded first look at the public repository, not a promise about maintainer response times or a prescribed contribution process. The repository is available under the Apache License 2.0. Check its current README, license, and project activity before you begin, since those sources are the authority for the current state.

Start with a bounded question

Instead of beginning with a broad goal such as “improve architecture diagrams,” write down one observable problem. Perhaps an element update accepts a confusing value, an export omits expected context, or a page makes an important control hard to find. A clear reproduction gives you a way to inspect behavior before changing it and a way to judge whether the result is better.

Read the README and the relevant documentation, then follow the call path into code. The repository’s top-level guide describes tld as an opinionated, flexible diagramming tool inspired by the C4 model. It documents Markdown notes, Mermaid integration, local YAML synchronization, editor and GitHub navigation, codebase mapping, and visualizing changes between Git revisions. Treat each capability as a specific workflow with its own implementation and docs; the README is an orientation, not a substitute for confirming details in the feature itself.

Learn the project’s shape

The repository’s architecture guide identifies cmd/ for CLI entry points and commands, internal/ for application internals, pkg/ for reusable packages, and frontend/ for the React interface. The Go module is github.com/mertcikla/tld/v2. The backend embeds the built frontend, so frontend changes may require building the UI before a Go binary can include the updated assets.

For data changes, inspect nearby migrations, store abstractions, and tests rather than assuming the application is SQLite-only. The documented store supports SQLite and PostgreSQL. The CLI can work directly against its database-backed target by default, and workspace YAML is read or written in workspace mode. These distinctions matter: a fix that only works for one persistence mode may not address the behavior you observed.

When the task concerns frontend behavior, the project’s guidance asks contributors to keep updates surgical because the shared UI is consumed by different wrappers. Find the owning component and its tests before broad refactoring. When a task crosses API boundaries, the repository guidance points to ConnectRPC and protocol definitions in a sibling repository, so verify the established path before introducing a new interface.

Build and check a local change

The README lists Go 1.26.2 or newer, Node.js 24, npm, and Make as build prerequisites. Its basic local path is:

The documented make build target builds the frontend and then compiles the binary with those assets embedded. For local development, the README describes installing Air, running make frontend-build, then make dev. Development data is kept under data/dev and configuration under data/dev/config in that workflow.

Choose checks that match the surface you changed. The repository documents make lint-be for Go linting, make lint-fe for frontend linting, make test for Go and frontend unit tests, and make test-e2e for Playwright end-to-end tests, which require browser binaries. Run the narrow relevant check while iterating, then the broader applicable checks before handing off. If a check needs external services or setup you do not have, say so precisely rather than implying it passed.

Make the review easy to understand

A focused patch usually tells a stronger story than a large cleanup bundled with a behavior change. Explain the observed problem, the chosen scope, and how you verified the result. Include a screenshot or a short reproduction when visual behavior is involved. For data or CLI changes, show a representative command and its output without exposing credentials or private architecture data.

The project’s documentation includes a diagram-authoring skill and CLI reference; these are useful examples of how the project expects tool workflows to be described. They do not define a universal contribution checklist, so check the repository’s current issue and pull request context for any extra expectations attached to a particular change.

Explore the tld source repository, its current README, and the CLI documentation for the latest details.