How a diagram is built.

Cartographer needs two sources because neither source describes the whole application. Eloquent models define relationships, while the database defines tables, columns, and keys.

The command combines both sources in five stages:

Find models → read the schema → find relationships → build the graph → write the file

Find the models

Cartographer scans the directories listed in cartographer.paths. A class is included when it:

• is declared in a scanned PHP file;
• extends Laravel's Model class;
• can be loaded by Composer;
• is not abstract.

The result is a sorted list of model classes. No database queries run during this stage.

See model discovery for paths, globs, and exclusions.

Read the database structure

Cartographer asks Laravel for the tables, columns, indexes, and foreign keys on the selected database connection.

It reads the current database instead of replaying migration files. This means the diagram also reflects squashed migrations, raw SQL migrations, and manual schema changes.

Different databases can report the same type under different names. Cartographer converts those names to a shared form. For example, PostgreSQL int8 and MySQL bigint both appear as bigint.

See schema introspection for supported types, keys, and database permissions.

Find the relationships

For each model, Cartographer calls public methods that take no required arguments. It keeps the methods that return an Eloquent Relation object.

Reading the relation object gives Cartographer the actual related model, foreign key, pivot table, and morph name. It does not need to guess them from method or column names.

Creating a relation object does not run its query. Cartographer never calls methods such as get() or first() on the relation.

This stage does run your model methods. See relationship detection before using relation methods with side effects.

Build the graph

Cartographer matches each model with its database table. A model without a table is skipped with a warning.

Each detected relationship becomes an edge between two tables. Many-to-many pivot tables become entities when they exist in the database.

The command then applies your scope:

1. Remove excluded models and relationship types.
2. Start from any seed models.
3. Follow relationships up to the requested depth.
4. Apply --only or a configured group.

A relationship can point outside a configured group. Cartographer keeps that edge and shows the outside table as a name without columns.

See scoping a diagram for the order of these controls.

Write the output

For Markdown output, Cartographer writes a Mermaid block that GitHub and GitLab can render. The file lists relationships first and entity blocks second.

For SVG and PNG output, Cartographer sends the Mermaid source to a local mermaid-cli installation. It keeps the source beside the image so cartographer:check can compare future output without running the renderer.

Cartographer writes through a temporary file in the destination directory. It then renames that file to the final path. If the command stops during the write, the previous diagram remains intact.

Why repeated runs produce the same file

Cartographer sorts models, tables, columns, relationships, entities, and edges before rendering them. It does not include a timestamp, host name, or random identifier.

Running the command twice with the same models and database therefore produces the same bytes. A Git diff changes only when an input changes.

What never happens

• Cartographer does not read rows from application tables.
• It does not run relation queries.
• It does not write to the database.
• It does not change files outside the configured output path and the temporary file used during writing.

What to read next

• Model discovery to understand which classes become entities.
• Relationship detection to understand which model methods Cartographer calls.
• Schema introspection to see how database types and keys become column details.
• PHP API to use the implementation classes directly.