Nivra: shared architecture for humans and AI

• 

  Nivra: result of changes

• 

  Nivra: issue found

• 

  Nivra: HLD view

• 

  Nivra: proposal solution

• 

  Nivra: final cut

• 

  Nivra: LLD view for Checkout

Inspiration

Software architecture is usually spread across diagrams, documentation, tickets, and conversations. Humans can understand the visual context, while AI agents often receive only screenshots or incomplete text descriptions.

We wanted to explore a different model: what if the architect and the agent could work inside the same structured architecture workspace?

That idea became Nivra.

What it does

Nivra is a shared visual architecture reasoning workspace for humans and AI agents.

The human works with an interactive architecture map. Through browser-native WebMCP tools, an agent can read the same underlying model, inspect components and dependencies, navigate between high-level and low-level views, record findings, create proposals, and validate architecture against explicit policies.

The demo begins with a Commerce Platform where Checkout appears to be independently deployable. Deeper inspection reveals hidden runtime coupling: Basket Adapter directly shares Product Store state across a deployment boundary without an explicit contract.

The agent surfaces the evidence, but the architectural decision remains with the human. The architect defines the required policy, and Nivra validates the Current Architecture deterministically. Current fails two of four rules.

Nivra then creates a separate remediation proposal that replaces the shared-state dependency with an explicit Checkout Snapshot Contract. The Proposal passes all four policies, while Current Architecture remains unchanged.

Why WebMCP

Nivra is not an AI assistant discussing a screenshot. WebMCP allows the application to expose structured architecture operations directly to an agent inside the same live page and browser session.

Nivra exposes seven WebMCP tools for:

• reading the active architecture;
• inspecting elements and relationships;
• opening and focusing architecture views;
• recording architectural findings;
• defining deterministic constraints;
• creating patch-based proposals;
• validating Current or Proposal architecture.

This makes agent actions inspectable, repeatable, and visible to the human through the Agent Activity timeline.

How we built it

Nivra is built with React, TypeScript, Vite, React Flow, Zustand, and browser-native WebMCP.

The architecture domain model is kept independent from the UI. React Flow renders the visual workspace, while Zustand manages interaction and persistence. WebMCP tools call the same validated workspace actions used by the human-facing interface.

Current Architecture is treated as immutable. Proposals are represented as patch-derived alternatives rather than destructive edits. Validation is deterministic and runs against the same policy rules for both Current and Proposal.

The project also includes automated unit tests and a repeatable browser-level WebMCP workflow that exercises the complete scenario multiple times from a canonical reset state.

Challenges we faced

One of the hardest challenges was making the agent experience meaningful without removing human control. The agent needed enough capability to inspect evidence and propose changes, while the architect still had to own policy and approval decisions.

We also had to ensure that:

• repeated agent calls remained idempotent;
• Current Architecture could never be accidentally overwritten;
• high-level and low-level views represented the same model;
• validation results were deterministic;
• agent operations were visible and understandable;
• the complete product story remained clear in a demo shorter than three minutes.

Working with an experimental browser API also required careful feature detection and graceful behavior in browsers where WebMCP is unavailable.

Accomplishments that we're proud of

We built a complete human-agent workflow rather than a technical proof of concept.

Nivra can move from architecture discovery to evidence, human policy, remediation proposal, deterministic validation, implementation planning, and a saved verified architecture branch—all inside one coherent workspace.

The original Current Architecture remains available throughout the entire process.

What we learned

The most important lesson was that agent-native applications need more than a chat interface. Agents become more useful when applications expose precise domain operations, stable identifiers, validated inputs, and observable outcomes.

We also learned that a strong human-agent experience is not about maximizing autonomy. It is about giving each participant the right responsibility: the agent discovers and structures evidence, while the human owns intent and architectural decisions.

What's next for Nivra

Future versions could add architecture imports, collaborative multi-user workspaces, durable server-side storage, real delivery-system integrations, and connections to source control, ADRs, and work-management platforms.

The long-term goal is to make architecture a living shared context for engineering teams and their agents.

Built With

• node.js
• react
• typescript
• vite
• vitest
• webmcp
• zustand