DSH Project Atlas

A read-only, evidence-aware architecture map where people and AI agents inspect the same project graph, trace verified paths, expose bypasses, and preserve uncertainty through WebMCP.

Comment

Inspiration

Large software projects become difficult to understand and control when screens, routes, permissions, services, data stores, audit rules, and runtime behavior drift apart.

Architecture diagrams become outdated, code searches show only fragments, and AI agents often have to reconstruct context from filenames, screen text, or incomplete documentation. This can hide duplicated rules, missing server-side checks, unknown consumers, and direct paths that bypass the approved architecture.

We built DSH Project Atlas to give people and AI agents one shared, evidence-aware view of a project.

What it does

DSH Project Atlas is a read-only architecture Explorer.

It represents a software project as a semantic graph containing user interfaces, browser routes, APIs, capabilities, backend handlers, owned data, audit contracts, and observed runtime evidence.

A person explores the graph visually, while an AI agent uses five structured WebMCP tools to work with the same exact entities:

  • inspect_project_overview;
  • focus_graph_entity;
  • trace_architecture_path;
  • list_security_findings;
  • compare_architecture_layers.

Atlas distinguishes verified relationships from Needs Proof, Unknown, Blind Spot, and Review states. It also keeps architectural bypasses visible instead of hiding them.

Unknown or fuzzy entity requests fail closed: Atlas rejects the request, changes nothing, and preserves the current selection.

Atlas is deliberately not an IDE or production control plane. It cannot edit code, execute SQL, modify databases, grant permissions, start builds, deploy releases, or access production. It gives an agent architectural insight without mutation authority.

How we built it

The shared interface is built with React and TypeScript.

The application registers five WebMCP tools through a literal document.modelContext.registerTool() boundary. Every tool has a closed JSON input schema, exact entity identifiers, bounded results, and no access to databases, credentials, shell commands, files, or deployment systems.

The repository also contains a dependency-free, project-neutral semantic graph core. It provides:

  • deterministic entity and relationship identifiers;
  • canonical JSON output;
  • SHA-256 integrity;
  • source provenance;
  • graph validation and querying;
  • explicit uncertainty;
  • conservative analyzers for JavaScript/React, Python, C#, SQL, and common service configuration.

The public demonstration uses a fully synthetic project called Orchid Commerce. It contains no customer data, employee data, credentials, private source code, or production information.

Orchid Commerce is a safe demonstration dataset, not a limitation of the engine. For a real project, the core can analyze an explicit allowlisted source manifest. A project-specific adapter can then add evidence-backed routes, APIs, capability IDs, ownership rules, policy contracts, audit relationships, and separately collected runtime observations.

Each project receives its own isolated namespace, graph artifact, and WebMCP allowlist.

Challenges we ran into

The most difficult challenge was representing uncertainty honestly.

A graph can look authoritative even when some relationships are inferred, incomplete, stale, or unsupported. We therefore made uncertainty a first-class part of the data model and interface.

Another challenge was making the agent useful without giving it dangerous authority. The WebMCP tools can change only the shared visual focus, path, findings view, and architecture comparison. They cannot mutate the project.

We also needed the human and agent experiences to remain synchronized. When the agent focuses an entity or traces a path, the person must see the same action immediately and be able to verify the conclusion.

Finally, we needed to fit a large capability map into one understandable workspace while keeping bypasses, blind spots, evidence, ownership, and security boundaries visually distinct.

Accomplishments that we're proud of

We are proud that Project Atlas:

  • gives people and AI agents one shared architecture map;
  • exposes capability paths and ownership boundaries;
  • visibly preserves bypasses and blind spots;
  • rejects unknown entities without changing state;
  • provides five bounded read-only WebMCP tools;
  • includes a reusable project-neutral semantic graph core;
  • supports deterministic and source-backed graph generation;
  • separates expected architecture from observed runtime behavior;
  • includes automated tests and a public-data boundary validator;
  • can be adapted to real projects without exposing private data;
  • is publicly released under the Apache License 2.0.

What we learned

AI collaboration becomes safer and more useful when context and authority are separated.

An agent does not need direct access to source code, databases, or production to help investigate architecture. It needs stable identities, verified relationships, provenance, and honest uncertainty.

We also learned that “not observed” must never be presented as “safe.” A candidate relationship must not become a verified architectural fact without reliable evidence.

WebMCP makes this collaboration practical because the agent receives structured project context while the person sees the same entities and actions in the interface.

What's next for DSH Project Atlas

Our next steps are:

  • a reusable loader for generated project graphs;
  • project-specific semantic adapters;
  • isolated multi-project namespaces;
  • richer provenance and ownership views;
  • controlled graph regeneration after verified code changes;
  • additional framework analyzers;
  • improved architecture history and comparison;
  • integration with DSH development workflows.

Developers and coding agents will continue to edit and test code in approved development environments. DSH or another controlled pipeline will regenerate the architectural evidence, and Atlas will display the resulting graph, deviations, bypasses, and unresolved unknowns.

Atlas will remain a read-only Explorer. Future development will improve its ability to explain and verify real projects without turning it into a privileged command channel.

Built With

Share this project:

Updates

Submission history