OpenMetadata CLAUDE.md

CLAUDE.md

Always-loaded guidance for every session. Language- and path-specific rules live in .claude/rules/*.md (auto-loaded when you touch matching files); procedures live in skills (loaded on invoke). This file is the map — see the pointer index at the bottom. Read ARCHITECTURE.md for the system map (modules, the request/ingestion/search paths, the invariants that hold); read DEVELOPER.md for how to build, test, and add an entity or connector (deep dives + end-to-end checklists). Consult docs/index.md — the knowledge index — to find existing design, plan, and reference docs for whatever area you're working on.

About OpenMetadata

OpenMetadata is a unified metadata platform for data discovery, observability, and governance — a multi-module project with a Java backend, a React/TypeScript frontend, a Python ingestion framework, and Docker infrastructure.

Stack at a glance

• Backend: Java 21 + Dropwizard, multi-module Maven.
• Frontend: React + TypeScript, built with Vite (dev server on :3000); component library openmetadata-ui-core-components — the UntitledUI + Tailwind v4 (tw: prefix, react-aria-components) go-forward design system; legacy stack is Ant Design + Less (deprecated). Machine-readable design-system specs: openmetadata-ui/src/main/resources/ui/specs/ (read specs/README.md before UI work).
• Ingestion: Python (>=3.10, no pinned ceiling; CI runs 3.10) + Pydantic 2.x, 75+ connectors.
• Database: MySQL (default) or PostgreSQL. Search: Elasticsearch 7.17+ or OpenSearch 2.6+.
• Infrastructure: Apache Airflow for ingestion orchestration.

Environment setup (every session)

• Python venv is REQUIRED before any Python work, make generate, or make install_dev*:

  source env/bin/activate          # first time: python3.11 -m venv env
  python --version                 # expect 3.10.x/3.11.x
  

  In a Claude Code worktree the venv is NOT copied — create one (python3.11 -m venv env && source env/bin/activate && cd ingestion && make install_dev) or symlink the main repo's (ln -s /path/to/main-repo/env env).
• One-call setup (macOS + Linux): make dev_setup (or ./scripts/dev_setup.sh) does everything below — toolchain, venv, generation, UI deps, pre-commit — and is idempotent. make dev_check diagnoses an existing checkout without changing it. See the dev-setup skill.
• First-time bootstrap (from the repo root — make generate is a root-only target; it does not exist under ingestion/):

  make prerequisites
  source env/bin/activate && cd ingestion && make install_dev_env && cd ..
  make generate                    # regenerate models after any schema change
  make yarn_install_cache
  make install_test precommit_install   # activate the commit-time format/license gate (pre-commit)
  

  The last line installs the pre-commit hooks (.pre-commit-config.yaml): on git commit they run Java format (spotless), Python format (ruff), UI format (prettier), design-token, and Apache-2.0 license checks on your changed files, matching CI. Do not skip them with --no-verify.
• Java: Java 21; use mvn. Frontend: use yarn (never npm); frontend root is openmetadata-ui/src/main/resources/ui/.
• Docker dev services: docker compose -f docker/development/docker-compose.yml up -d.