The Problem

Teams working with large databases struggle to understand their schemas. Existing ER diagram tools require manual configuration, export processes, or paid services, making it hard to get a quick, accurate visual of what the database actually looks like.

What This Does

Liam ERD automatically generates interactive ER diagrams from database schemas. It reverse-engineers schema files (SQL, Ruby, Prisma) into clean, navigable diagrams. The core logic lives in frontend/packages/erd-core/ and frontend/packages/schema/, with a Next.js application in frontend/apps/app/ providing the UI.

The repo is a fork of liam-hq/liam (5,087 stars upstream). It's a monorepo using pnpm, with the frontend as the primary project (2,067 of 2,175 files). The stack is TypeScript (977 files), React, Next.js, Tailwind, and LangChain for AI-assisted features.

How It Is Wired

Execution starts in the Next.js app at frontend/apps/app/app/page.tsx. The routing structure handles project, branch, and schema file paths via frontend/apps/app/app/projects/[projectId]/ref/[branchOrCommit]/schema/[...schemaFilePath]/page.tsx. The [...slug] catch-all in frontend/apps/app/app/erd/p/[...slug]/ handles public schema viewing—inserting liambx.com/erd/p/ into a GitHub URL triggers the diagram.

The renderer is frontend/packages/erd-core/src/features/erd/components/ERDRenderer/ErdRenderer.tsx. The store at frontend/packages/erd-core/src/stores/index.ts is the hub: 64 modules depend on it (highest in the codebase), making it the highest-blast-radius file. The server DB layer at frontend/apps/app/libs/db/server.ts (57 importers) is similarly central.

There are 57 modules in circular dependencies. The most significant cycle is in frontend/packages/schema/src/migrationOperation/schema/index.ts (37 importers, in cycle). Changing any file in that cycle risks subtle breakage elsewhere.

The wiring for the AI agent and LangChain features is not fully mapped in this analysis; the module graph doesn't trace those paths.

How To Use It

Setup:

git clone https://github.com/moses-y/liam
cd liam/frontend
pnpm install

Configuration: The app expects environment variables in frontend/apps/app/.env. A template exists at .env.template in the root. Note: the repo has committed .env, .env.local, and .env.production files—you'll want to replace these with your own values before running.

Running it:

pnpm dev

The README documents a zero-install path: for public repos, just prepend liambx.com/erd/p/ to a schema file URL on GitHub. For private repos, npx @liam-hq/cli init runs an interactive setup.

Real-World Use

A team with a Rails app can point Liam at db/schema.rb in a public repo. Anyone with the URL gets an interactive diagram—no local setup. For private repos, the CLI handles auth and fetches the schema server-side. The tool handles 100+ tables without performance degradation, making it viable for production-scale schemas.

Code Health & Issues

Static analysis found 113 issues (66 high, 40 medium, 7 low) across 4 kinds:

  • High – Import cycle members (34 instances): frontend/packages/schema/src/migrationOperation/schema/index.ts and related files participate in circular imports. Fix: extract shared types or invert dependencies.
  • High – Hub modules (20 instances): frontend/packages/erd-core/src/stores/index.ts (64 dependents) and frontend/apps/app/libs/db/server.ts (57 dependents) are high-churn, high-blast-radius. Keep them stable.
  • High – Deep nesting (5 instances): frontend/apps/app/components/ShareDialog/ShareDialog.tsx reaches indentation depth 8. Fix with guard clauses.
  • High – Duplicated code (156 repeated 6-line blocks across 95 files): Layout files like frontend/apps/app/app/projects/layout.tsx repeat identical structure. Extract shared helpers.

The code health audit adds:

  • High – Committed secrets: frontend/apps/app/.env, .env.local, .env.production are tracked despite .gitignore rules. The .env.local file is explicitly ignored but committed. Rotate all credentials and git rm --cached these files.
  • High – CI doesn't run tests: 159 test files exist, but the 2 workflows read have no test command. A green check doesn't mean assertions ran.
  • Medium – No dependency vulnerability scan in CI.
  • Medium – No pre-commit secret gate.
  • Medium – Large binaries: share.gif (14.2MB) and demo.gif (13.8MB) bloat every clone. Use Git LFS.
  • Low – No timeout-minutes on workflow jobs; missing .editorconfig and .gitattributes.

The Bottom Line

The core product is solid: the ERD rendering and schema parsing are well-architected, and the zero-config public URL feature is genuinely useful. The fork's value is unclear—it appears to be a near-copy of the upstream with no obvious differentiators. The committed secrets and untracked test suite are the most urgent fixes; address those before any production deployment.