master_architect

The project map. It indexes a codebase and keeps the index current on every save, so read_file can show files, functions and how they connect before a single line is read.

Components

How it works

master_architect scans a project and stores it as a graph in SQLite: every file, module, function and import, plus the databases, programs and servers the code refers to. Every save re-indexes the saved file in every supported language, so the graph never lags behind the disk. The agent never calls it directly: read_file asks it.

Coordinates

Folders and files get letters, one sequence per folder: subfolders first, then files. What is inside a file gets numbers. d.a.f.31.17 reads as folder src, folder itsdangerous, file signer.py, segment 31.17: the method verify_signature. One coordinate takes the agent from the project straight to the code in a single call.

What read_file gets from it

• scan: automatic, when a repository is cloned or a folder is first read, and per file on every save.
• structure: a project's folders and files with coordinates, language and size.
• data flow: which files import which, plus the databases, programs and servers they use.
• connections: one file's links in and out, and imports that lead nowhere.
• database facts: each SQL query linked to the database it runs on, so it can be checked against the live schema.

Python environments

• A project inside a Python virtual environment uses the venv folder as its root. The venv's own machinery (bin, lib, site-packages) is never indexed, only the project's code.
• A venv inside a project is left out of the index and reported in the project structure.
• Package checks look inside the project's venv, the way Python would at run time. Nothing from the project folder is ever executed to do so.

Why it is built this way

• SQLite keeps the graph self-contained: no database server, and it handles graphs with hundreds of thousands of items.
• Coordinates are short enough to pass between tool calls and say where something is at a glance: letters for location, numbers for code.
• Import resolution follows real project layouts: packages, plain sibling imports in script folders, and src/ layouts. An import rooted in the project that resolves to nothing is reported as broken, instead of being mistaken for an external library.

In the sandbox

Scanning is limited to your sandbox, and your project map is stored inside it, so it disappears with the sandbox.