ProjectGraphAgent Demonstration: When Artificial Intelligence Models Recommend Jsonnet for Codebase Architecture

[Igor Lebedev]

Hello to the Jsonnet community,

I would like to share an experimental project for creating a "live" architectural model called ProjectGraphAgent, and I think this is a fascinating example of using Jsonnet. What makes the system interesting for this group is that Jsonnet was chosen as the base technology based on direct recommendations from several LLMs (Gemini, Claude, GPT-4, Perplexity, Grok, DeeplSeek, Qwen) when I was thinking about this system and consulted with various LLMs.

The repository on GitHub: https://github.com/LebedevIV/ProjectGraphAgent

The goal was to create a "living" architectural model of a software project — a single source of reliability that could be used primarily by AI agents to maintain architectural integrity. The system needed to identify the components, their relationships, and policies, and then audit the actual codebase according to that definition.

Why Jsonnet? Justification of AI.
I have familiarized AIs with the system requirements, requesting the best configuration language for this task, which will be used exclusively by AI agents without human intervention (or with minimal participation to fill in some input data). They invariably pointed to Jsonnet in comparison with YAML, XAML, Dhall, CUE, or even just JSON and other variants. In their reasoning, they identified several key advantages that make it ideal for this task.:
Declarative in nature: Ideal for determining the desired state or "fundamental truth" for the architecture of a project, without getting bogged down in imperative logic.
Modularity: The ability to import and structure a graph into logical parts (entities.jsonnet, relations.jsonnet, policies.jsonnet) was crucial for managing complexity.
Data Templating: Functions and templates are widely used to reduce boilerplate when defining hundreds of files and components, ensuring consistency.
Guaranteed JSON output: The important thing is that it compiles into pure, machine-readable JSON. This output is used directly by AI assistants and automation scripts that perform audits and commits.

How it works: Declared or not. Observed
The core of ProjectGraphAgent is the "Declared and Observed" paradigm:
Declared state: The entire architecture of the project is defined in files.jsonnet. This is a man-made "map" of the project.
Observable state: Simple adapters scan the actual file system to see what's really there.
Deviation detection: The system compares the two states and reports any deviation, instantly marking on the graph undocumented files or components that have been deleted but not updated.
Here is a simplified example of its structure:

// In graph_parts/templates.jsonnet { FileEntity(path, purpose, tags=[]) :: { type: 'File', path: path, purpose: purpose, tags: tags, metadata: { timestamp: std.extVar('timestamp') } } } // In project_graph.jsonnet local templates = import 'graph_parts/templates.jsonnet'; { entities: { 'package.json': templates.FileEntity( path: 'package.json', purpose: 'Defines project dependencies and scripts.', tags: ['build', 'config'] ), 'src/main.ts': templates.FileEntity( path: 'src/main.ts', purpose: 'The main entry point for the application.' ), } }

I am talking about this here because it is a practical, artificial intelligence-based confirmation of Jsonnet's capabilities in the field of system configuration and modeling. It's still in the early stages of alpha testing and is more of a hobby and a side project for me, but I think it's a powerful demonstration of the language's capabilities.

I would be very interested to hear your thoughts, feedback, or suggestions on this use case.

Thank you, 

Igor Lebedev

[Brett Viren]

HI Igor,

This looks interesting to me but I admit I do not fully get what the
intention is here so I can only offer a few surface thoughts.

- It looks like a lot of detailed information to encode. I would not
want to hand-edit all this info. Best if the graph can be
automatically generated by some program that examines the source
(maybe with LLM help). I guess at least some of the relationships can
be formed by a code scanner such as what waf.io (and others) uses to
figure out build dependencies.
- For me personally, when I see "npm" or "node", I normally close the
browser tab and move on. I know my bias is unfair and subjective and
that for those using TypeScript npm and node are a given but still I
guess basing on npm/node will limit your audience (not necessarily a
bad thing!).
- Instead of using std.extVar("timestamp") consider generating a
JSON/Jsonnet file that maps file names to their latest timestamp (or
perhaps a more full structure of values - permissions, size,
ownership, etc) and then `import` that file to use as needed in the
Jsonnet. Regeneration of this file would probably best be part of an
overall build system.

Cheers and best of luck,
-Brett.

> --
> You received this message because you are subscribed to the Google Groups "Jsonnet" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to jsonnet+u...@googlegroups.com.
> To view this discussion visit https://groups.google.com/d/msgid/jsonnet/450175c5-2afe-4d7e-a124-d13c5e33d378n%40googlegroups.com.

[Igor Lebedev]

Thanks, Brett! Greetings!

I probably couldn't accurately convey the idea of ProjectGraphAgent: it is designed to maximize the automation of the management of a project that is being developed using AI agents (for example, I work at Cursor and VSCode). The folder with ProjectGraphAgent is placed in the root directory of the project, and then the AI agent is instructed to study it, and it contains an invitation for the AI agent with instructions, after which the AI agent, following the instructions, creates a map (graph) of the project, similar to a memory bank, but not in the form of markdown files, but based on jsonnet, which is much more convenient for AI agents and LLM and allows you to take into account the relationships as UML did. Only UML was focused on people, and jsonnet was exclusively focused on AI agents.  In the process of working on a project, hooks are launched after each committee, which force the AI agent to analyze the changes and commit them to the ProjectGraphAgent structure in the corresponding jsonnet files.
It's a bit raw, but in my opinion it worked clearly better than the memory-bank for my other project, it even seems to have some impact, everything went well on GPT-5. This system does not change the project itself in any way - just a folder inside the project, but it is able to create some kind of active memory-bank, much more understandable for AI-agent and LLM than markdown files - that's what the AIS themselves claim.
I tried to yell with waf.io to look at the code scanner there, but I haven't found it yet, and perplexity-type AI didn't help me much either)) Maybe I misunderstood something from your answer?

And all the best to you,
Igor