Next.js architecture diagram: the system around the app, drawn from the repo

package.json is the densest architecture file in a JavaScript repository, and it is classified as a dependency manifest with a ceiling of 8, which is what lets a workspace repo contribute the root manifest and several package manifests to the same corpus. The dependency list names the database client, the ORM, the auth library, the payment provider, the mail sender, the queue, the analytics, and the model SDKs. Almost every external node in the finished diagram traces back to a line in that file.

The data layer comes from its own classes. A file named schema.prisma has a class to itself, 2 files. Migrations under a directory named migrations get 6 slots, sampled three from the earliest files and three from the latest, so the initial shape and the current direction both reach the generator. Plain .sql files elsewhere are classified separately, with 10 slots of their own.

The contract layer comes from the API class, and the matching rule is worth checking against your repo: a file is an API definition when its name starts with openapi. or swagger., or when its extension is .graphql, .gql, or .proto. A specification kept as docs/api-spec.yaml matches none of those and is read only if something else classifies it, so naming it openapi.yaml is the cheapest way to get the contract into the diagram.

The deployment path comes from the CI class: anything under .github/workflows, a root .gitlab-ci.yml, or an azure-pipelines file, plus any Dockerfile or compose file the repository carries.

What a Next.js repo contributes
  package.json              dependency manifest class (names the providers)
  prisma/schema.prisma      schema class
  prisma/migrations/*.sql   migration class (sampled from both ends)
  graphql/schema.graphql    API class
  Dockerfile                container class
  .github/workflows/*.yml   CI class

Never walked
  node_modules/  .next/  dist/  coverage/  and every lockfile

TypeScript source is not part of the classified corpus, so the route handlers under app/api and the server actions in your components are not fetched. What the generator sees of them is the tree summary: app/api/ with its file count, and every other directory to three levels with theirs.

That sounds like a loss until you consider what a diagram made from route files would look like. Four hundred boxes, one per handler, is not architecture. The dependency manifest, the schema, and the pipeline describe the system at the altitude a diagram is actually read at, which is why they are the ones classified.

node_modules and .next are on the skip list and are never walked, and every lockfile is dropped by name, so a repository with a 4MB pnpm lock spends none of its 40-file budget on it.

On the first sync, Datadef counts what it classified and proposes a focus in one sentence built from those counts alone, with no model call. A typical application repo reads as: Mostly Dockerfiles and CI pipelines (9 files) with 5 data model and API files. Architecture is the usual pick, and it draws the running system: the app, its database, the providers, the jobs, and the pipeline that deploys them.

The content focus is the alternative, and it is the right choice when the interesting part of the repository is the data model rather than the deployment. It raises the ceilings on schemas, migrations, and API definitions and treats the containers and pipelines as context.

Either way the output lands on an editable canvas, so the two or three things only you know, a rate limit, a webhook path, an ownership boundary, can be added as annotations and survive on the diagram.

The connection re-syncs daily against the branch or tag you chose, and skips commits that did not move the head. Adding a provider is usually a package.json change, which is exactly the kind of change that ought to redraw an architecture diagram and almost never does when the diagram lives in a design tool.

Embed the result in the repository README as a live image and the onboarding paragraph gets a picture that matches main. Export stays available as PNG or JPEG for a slide or a review document.

• React application architecture generator
• Keep the README in sync with the code
• Monorepo architecture diagram
• Repo to diagram: repository sync