How Engineers and System Thinkers Use Wity

Engineers think in systems by default. Dependencies, data flows, failure modes, tradeoffs between consistency and performance — these are the natural units of thought for anyone who designs software at the architecture level. What engineers often lack is not the thinking but the infrastructure to make that thinking visible, persistent, and shareable with the people who need to understand it.

A system architecture that exists primarily in one person's head is a organisational liability. An architecture that's been mapped, documented with decision rationale, and made interrogatable is a foundation. Wity (wity.ai) is the environment where that translation from mental model to shared artifact happens — and where AI agents extend what a single engineer can research, review, and document in a day.

Visual Architecture Mapping Before the Code

The standard documentation approach for system architecture is the architecture diagram: boxes, arrows, labels. These are useful but limited. They show the structure but not the reasoning. Why is this service synchronous rather than event-driven? Why does this data live in Postgres rather than the service's local state? Why is this boundary here rather than there? The diagram doesn't carry this information. The reasoning is in someone's head, occasionally in a Confluence doc that's two versions out of date.

Wity's visual canvas (app.wity.ai) maps architecture differently because it's a thinking environment rather than a documentation environment. You're not drawing a final diagram — you're mapping a set of decisions in progress. A node for each service, connected by nodes representing the decisions about how they interact, each decision node connected to the context that produced it: the requirements, the constraints, the alternatives that were considered and rejected.

A practical starting point: before beginning work on a new service or a significant refactor, open a canvas and map the problem space. What does this service need to do? What are its consumers? What are the consistency requirements at each boundary? What does failure look like, and what should happen when it occurs? This isn't just documentation — it's the thinking that produces better design decisions, made explicit and visible before the code is written.

Architecture Decision Records: Capturing Why, Not Just What

Architecture Decision Records (ADRs) are well-established in mature engineering organisations. The idea is simple: when you make a significant architectural decision, write a short document capturing the context, the options considered, the decision made, and the rationale. This creates a searchable record of why the system is the way it is, which is invaluable when someone new joins the team, when the decision needs to be revisited, or when a related decision needs to draw on established reasoning.

The problem is that ADRs, when written after the fact, are reconstructions. The actual reasoning happened in a Slack thread, a design review meeting, and a few long-form thinking sessions by the lead engineer. The ADR captures a clean narrative version of a messier process, and some of the most important context — the alternatives seriously considered, the specific constraints that ruled them out — gets simplified or omitted.

Wity's canvas is the place where the actual reasoning happens, which means the ADR can be generated from the canvas rather than reconstructed from memory. The alternatives are already mapped. The constraints are already connected to the options they ruled out. The decision is already placed in the context of the broader system. Generating the ADR document from this material produces a more complete and honest record than writing it cold.

AI Agents from the CLI: Engineering Workflows Without Leaving the Terminal

Wity's AI agents are accessible from the command line via the npm @wityai/agents-cli package. For engineers who live in the terminal, this is a significant difference from browser-based AI tools: you don't leave your workflow to access the capability.

What can you run as a CLI agent? Code review workflows that go beyond linting — semantic review against your architecture principles and patterns. Documentation generation that produces docstrings, README sections, or API reference from code context. Architecture research on a specific design question: "what are the established patterns for handling distributed saga orchestration in a Node.js microservices environment, and what are the failure modes of each?" This runs as an async task, results arrive in your terminal, and you're consuming the output in the same environment you're working in.

The agents are composable. An agent that generates an ADR from a canvas, combined with an agent that posts that ADR to the team's Confluence and notifies the relevant Slack channel, becomes a lightweight automation for a high-value engineering practice that most teams do inconsistently because the friction is too high.

Multi-Model AI Chat with Your Own Architecture Docs

Wity's AI chat (chat.wity.ai) connects to your own knowledge base — your architecture documents, your ADRs, your API references, your internal design guidelines. This is not a generic ChatGPT session. It's a conversation with an AI that has read and indexed the specific system you work on.

For engineers, the practical applications are significant. "Which services currently depend on the user-preferences service and would be affected by a schema change?" is a question that normally requires grepping across repos and reading a lot of code. With your architecture docs indexed in Wity chat, it's a conversation query. "What was the rationale for using event sourcing in the orders domain?" returns the reasoning from the relevant ADR, connected to the context that produced it. "What are the consistency guarantees at the boundary between the inventory service and the order service?" returns the answer from your documented architecture, or surfaces a gap where the answer isn't documented — which is itself useful information.

A Real Example: Microservices Migration

A backend engineering lead is planning a migration from a modular monolith to a microservices architecture for a logistics platform. The migration will take six months and touch every part of the system. The risk of doing it badly — creating distributed monolith instead of genuine microservices, or cutting service boundaries at the wrong places — is high.

They start with a Wity canvas. The monolith's modules become nodes. The relationships between modules — shared data, synchronous calls, event dependencies — become mapped connections. Immediately, the canvas reveals something the mental model had obscured: three of the modules share a data model that they thought was clean but is actually a tight coupling point that will make independent deployment difficult without first refactoring that model.

An AI agent runs overnight, researching the established patterns for decomposing logistics and supply chain monoliths, and the specific failure patterns that emerge when teams cut microservice boundaries along organisational lines rather than domain logic lines. The research lands in the canvas as connected reference nodes.

The resulting migration plan identifies the data model refactor as phase one — before any service extraction — because the canvas made the coupling visible and the agent research confirmed that skipping this step is the most common failure mode in this class of migration. The ADR for this decision, generated from the canvas, is the most complete decision record this team has ever produced, because the reasoning was built in Wity rather than reconstructed from memory.

The System Thinker's Tool

Engineers don't need tools that make simple things slightly faster. They need tools that match the complexity of the problems they're solving — systems thinking for system design, persistent reasoning for decisions that compound over years, AI capabilities that integrate into terminal-based workflows rather than demanding context switches. Wity is built for exactly this mode of work.