dify/AGENTS.md

AGENTS.md

Project Overview

Dify is an open-source platform for developing LLM applications with an intuitive interface combining agentic AI workflows, RAG pipelines, agent capabilities, and model management.

The codebase is split into:

• Backend API (/api): Python Flask application organized with Domain-Driven Design
• Frontend Web (/web): Next.js 15 application using TypeScript and React 19
• Docker deployment (/docker): Containerized deployment configurations

Backend Workflow

• Run backend CLI commands through uv run --project api <command>.

• Backend QA gate requires passing make lint, make type-check, and uv run --project api --dev dev/pytest/pytest_unit_tests.sh before review.

• Use Makefile targets for linting and formatting; make lint and make type-check cover the required checks.

• Integration tests are CI-only and are not expected to run in the local environment.

Frontend Workflow

cd web
pnpm lint
pnpm lint:fix
pnpm test

Testing & Quality Practices

• Follow TDD: red → green → refactor.
• Use pytest for backend tests with Arrange-Act-Assert structure.
• Enforce strong typing; avoid Any and prefer explicit type annotations.
• Write self-documenting code; only add comments that explain intent.

Language Style

• Python: Keep type hints on functions and attributes, and implement relevant special methods (e.g., __repr__, __str__).
• TypeScript: Use the strict config, lean on ESLint + Prettier workflows, and avoid any types.

General Practices

• Prefer editing existing files; add new documentation only when requested.
• Inject dependencies through constructors and preserve clean architecture boundaries.
• Handle errors with domain-specific exceptions at the correct layer.

Project Conventions

• Backend architecture adheres to DDD and Clean Architecture principles.
• Async work runs through Celery with Redis as the broker.
• Frontend user-facing strings must use web/i18n/en-US/; avoid hardcoded text.