Dify.ai

# MISSION: Scaffold "Dify.ai" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Dify.ai**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Dify.ai
- **What It Does**: Dify is an open-source LLM application platform combining a visual workflow builder, RAG pipelines, and AI agents with model management and observability, deployable self-hosted via Docker or on Dify Cloud.
- **Domain & Category**: LLM App Builder
- **Production Scale**: 20+ people
- **Development Mode**: AI-AGENT
- **Architectural Rationale**: Agent execution and vector retrieval are split into separate, independently scalable services (a Go sandbox runtime, a FastAPI agent orchestrator, and pluggable vector-store providers) so untrusted tool code and swappable retrieval backends stay out of the core Flask API process.
- **Live Website Reference**: https://dify.ai
- **Source Repository**: https://github.com/langgenius/dify
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Next.js, TypeScript, Python, Flask, Celery, Redis, PostgreSQL, Go, Docker
- **Primary Language(s)**: TypeScript, Python, JavaScript
- **License of the reference repo**: NOASSERTION
- **Frontend**: Next.js — Serves the Studio console and end-user app UI; scripts and web/next.config.ts drive the standard build.; Vite — Powers an experimental "vinext" dev/build path (dev:vinext, build:vinext scripts) alongside the Next.js build.; Jotai + TanStack Form — Shared atom-based state and form bindings, packaged as an in-repo workspace library for the web app.; dify-ui (@base-ui/react + Tailwind) — Dify's own component package (buttons, dialogs, comboboxes) built on @base-ui/react, shared by web and packages/dify-ui.
- **Backend & APIs**: Flask — Runs the console/service REST API; app.py and app_factory.py bootstrap the WSGI app served by Gunicorn.; Celery — Executes background jobs (workflow runs, document indexing) via a dedicated entrypoint and scheduler.; Gunicorn + gevent — Production WSGI server using gevent workers and gevent-websocket for the Flask API process.; dify-agent (FastAPI + pydantic-ai) — Standalone Python service that runs autonomous agents, separate from the main Flask API process.; dify-agent-runtime (Go) — Sandboxed shell/file execution backend for agents, using landlock-lsm for OS-level isolation.
- **Data & persistence**: PostgreSQL — Primary relational store, accessed via psycopg2-binary from the Flask API and Celery workers.; Redis — Celery broker/result backend and general cache, via redis[hiredis].; Pluggable vector stores — RAG retrieval backends are workspace packages under api/providers/vdb, with pgvector, Elasticsearch, and TiDB deployable via Docker.
- **Infrastructure & deploy**: Docker Compose — Self-hosted stack is assembled from docker/docker-compose.yaml plus per-service env files.; Nginx — Reverse proxy in front of the web and api containers for self-hosted deployments.; SSRF proxy — Dedicated proxy container that outbound tool/plugin HTTP calls are routed through to contain SSRF risk.
- **Tooling, testing & ops**: pydantic-ai — Agent orchestration framework used by the dify-agent service for tool calling and multi-step reasoning.; e2b — Optional cloud sandbox provider for agent code execution, alongside the local Go landlock sandbox.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/langgenius/dify @ ad9a5be)
1. **Agent execution is split into two services outside the main API**: dify-agent (Python, FastAPI + pydantic-ai, dify-agent/pyproject.toml) orchestrates agent reasoning, while dify-agent-runtime (Go, dify-agent-runtime/go.mod) runs shell and file operations inside a landlock-lsm sandbox. Neither runs inside the Flask api process that serves normal console/app requests.
2. **The web console can build with Next.js or an experimental Vite path**: web/package.json defines both the standard "build"/"dev" scripts (next build, next dev) and "build:vinext"/"dev:vinext" scripts that go through web/vite.config.ts, so the same app/ directory can be served by either toolchain during the transition.
3. **Vector store backends are pluggable provider packages, not a hard dependency**: api/pyproject.toml declares a uv workspace over providers/vdb/*, and docker/ ships separate compose fragments for pgvector, Elasticsearch, TiDB, and Couchbase, so operators choose a retrieval backend at deploy time rather than the API hard-coding one vector database client.
4. **Outbound tool calls go through a dedicated SSRF proxy container**: docker/ssrf_proxy is a separate service in the compose stack that HTTP requests originating from tools, plugins, and code-execution nodes are routed through, keeping arbitrary user-configured URLs from reaching internal services directly.
5. **The CLI is a separate TypeScript package compiled to native binaries**: cli/package.json builds @langgenius/difyctl with vite-plus and ships per-platform bun targets (linux-x64, darwin-arm64, windows-x64, etc.) rather than requiring a Node/Python runtime on the operator machine.
6. **API-consumer SDKs live in the monorepo but ship independently**: sdks/nodejs-client (dify-client, published to npm) and sdks/php-client are versioned and published separately from the main app/api images, giving external integrators a stable client without depending on the app release cadence.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Utilize Next.js 15 App Router: default to React Server Components (RSC) for data fetching. Handle mutations through Server Actions with Zod validation. Keep 'use client' directives restricted strictly to interactive leaf components.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (PostgreSQL, Redis, Pluggable vector stores): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.