Underground-Digital/Workflow-Engine

1So you're looking to contribute to Dify - that's awesome, we can't wait to see what you do. As a startup with limited headcount and funding, we have grand ambitions to design the most intuitive workflow for building and managing LLM applications. Any help from the community counts, truly.2 3We need to be nimble and ship fast given where we are, but we also want to make sure that contributors like you get as smooth an experience at contributing as possible. We've assembled this contribution guide for that purpose, aiming at getting you familiarized with the codebase & how we work with contributors, so you could quickly jump to the fun part. 4 5This guide, like Dify itself, is a constant work in progress. We highly appreciate your understanding if at times it lags behind the actual project, and welcome any feedback for us to improve.6 7In terms of licensing, please take a minute to read our short [License and Contributor Agreement](./LICENSE). The community also adheres to the [code of conduct](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md).8 9## Before you jump in10 11[Find](https://github.com/langgenius/dify/issues?q=is:issue+is:open) an existing issue, or [open](https://github.com/langgenius/dify/issues/new/choose) a new one. We categorize issues into 2 types:12 13### Feature requests:14 15* If you're opening a new feature request, we'd like you to explain what the proposed feature achieves, and include as much context as possible. [@perzeusss](https://github.com/perzeuss) has made a solid [Feature Request Copilot](https://udify.app/chat/MK2kVSnw1gakVwMX) that helps you draft out your needs. Feel free to give it a try.16 17* If you want to pick one up from the existing issues, simply drop a comment below it saying so.18 19  20 21  A team member working in the related direction will be looped in. If all looks good, they will give the go-ahead for you to start coding. We ask that you hold off working on the feature until then, so none of your work goes to waste should we propose changes.22 23  Depending on whichever area the proposed feature falls under, you might talk to different team members. Here's rundown of the areas each our team members are working on at the moment:24 25  | Member                                                       | Scope                                                |26  | ------------------------------------------------------------ | ---------------------------------------------------- |27  | [@yeuoly](https://github.com/Yeuoly)                         | Architecting Agents                                  |28  | [@jyong](https://github.com/JohnJyong)                       | RAG pipeline design                                  |29  | [@GarfieldDai](https://github.com/GarfieldDai)               | Building workflow orchestrations                     |30  | [@iamjoel](https://github.com/iamjoel) & [@zxhlyh](https://github.com/zxhlyh) | Making our frontend a breeze to use                  |31  | [@guchenhe](https://github.com/guchenhe) & [@crazywoola](https://github.com/crazywoola) | Developer experience, points of contact for anything |32  | [@takatost](https://github.com/takatost)                     | Overall product direction and architecture           |33 34  How we prioritize:35 36  | Feature Type                                                 | Priority        |37  | ------------------------------------------------------------ | --------------- |38  | High-Priority Features as being labeled by a team member     | High Priority   |39  | Popular feature requests from our [community feedback board](https://github.com/langgenius/dify/discussions/categories/feedbacks) | Medium Priority |40  | Non-core features and minor enhancements                     | Low Priority    |41  | Valuable but not immediate                                   | Future-Feature  |42 43### Anything else (e.g. bug report, performance optimization, typo correction):44 45* Start coding right away.46 47  How we prioritize:48 49  | Issue Type                                                   | Priority        |50  | ------------------------------------------------------------ | --------------- |51  | Bugs in core functions (cannot login, applications not working, security loopholes) | Critical        |52  | Non-critical bugs, performance boosts                        | Medium Priority |53  | Minor fixes (typos, confusing but working UI)                | Low Priority    |54 55 56## Installing57 58Here are the steps to set up Dify for development:59 60### 1. Fork this repository61 62### 2. Clone the repo63 64 Clone the forked repository from your terminal:65 66```67git clone git@github.com:<github_username>/dify.git68```69 70### 3. Verify dependencies71 72Dify requires the following dependencies to build, make sure they're installed on your system:73 74- [Docker](https://www.docker.com/)75- [Docker Compose](https://docs.docker.com/compose/install/)76- [Node.js v18.x (LTS)](http://nodejs.org)77- [npm](https://www.npmjs.com/) version 8.x.x or [Yarn](https://yarnpkg.com/)78- [Python](https://www.python.org/) version 3.10.x79 80### 4. Installations81 82Dify is composed of a backend and a frontend. Navigate to the backend directory by `cd api/`, then follow the [Backend README](api/README.md) to install it. In a separate terminal, navigate to the frontend directory by `cd web/`, then follow the [Frontend README](web/README.md) to install.83 84Check the [installation FAQ](https://docs.dify.ai/learn-more/faq/install-faq) for a list of common issues and steps to troubleshoot.85 86### 5. Visit dify in your browser87 88To validate your set up, head over to [http://localhost:3000](http://localhost:3000) (the default, or your self-configured URL and port) in your browser. You should now see Dify up and running. 89 90## Developing91 92If you are adding a model provider, [this guide](https://github.com/langgenius/dify/blob/main/api/core/model_runtime/README.md) is for you.93 94If you are adding a tool provider to Agent or Workflow, [this guide](./api/core/tools/README.md) is for you.95 96To help you quickly navigate where your contribution fits, a brief, annotated outline of Dify's backend & frontend is as follows:97 98### Backend99 100Dify’s backend is written in Python using [Flask](https://flask.palletsprojects.com/en/3.0.x/). It uses [SQLAlchemy](https://www.sqlalchemy.org/) for ORM and [Celery](https://docs.celeryq.dev/en/stable/getting-started/introduction.html) for task queueing. Authorization logic goes via Flask-login. 101 102```103[api/]104├── constants             // Constant settings used throughout code base.105├── controllers           // API route definitions and request handling logic.           106├── core                  // Core application orchestration, model integrations, and tools.107├── docker                // Docker & containerization related configurations.108├── events                // Event handling and processing109├── extensions            // Extensions with 3rd party frameworks/platforms.110├── fields                // field definitions for serialization/marshalling.111├── libs                  // Reusable libraries and helpers.112├── migrations            // Scripts for database migration.113├── models                // Database models & schema definitions.114├── services              // Specifies business logic.115├── storage               // Private key storage.      116├── tasks                 // Handling of async tasks and background jobs.117└── tests118```119 120### Frontend121 122The website is bootstrapped on [Next.js](https://nextjs.org/) boilerplate in Typescript and uses [Tailwind CSS](https://tailwindcss.com/) for styling. [React-i18next](https://react.i18next.com/) is used for internationalization.123 124```125[web/]126├── app                   // layouts, pages, and components127│   ├── (commonLayout)    // common layout used throughout the app128│   ├── (shareLayout)     // layouts specifically shared across token-specific sessions 129│   ├── activate          // activate page130│   ├── components        // shared by pages and layouts131│   ├── install           // install page132│   ├── signin            // signin page133│   └── styles            // globally shared styles134├── assets                // Static assets135├── bin                   // scripts ran at build step136├── config                // adjustable settings and options 137├── context               // shared contexts used by different portions of the app138├── dictionaries          // Language-specific translate files 139├── docker                // container configurations140├── hooks                 // Reusable hooks141├── i18n                  // Internationalization configuration142├── models                // describes data models & shapes of API responses143├── public                // meta assets like favicon144├── service               // specifies shapes of API actions145├── test                  146├── types                 // descriptions of function params and return values147└── utils                 // Shared utility functions148```149 150## Submitting your PR151 152At last, time to open a pull request (PR) to our repo. For major features, we first merge them into the `deploy/dev` branch for testing, before they go into the `main` branch. If you run into issues like merge conflicts or don't know how to open a pull request, check out [GitHub's pull request tutorial](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests). 153 154And that's it! Once your PR is merged, you will be featured as a contributor in our [README](https://github.com/langgenius/dify/blob/main/README.md).155 156## Getting Help157 158If you ever get stuck or got a burning question while contributing, simply shoot your queries our way via the related GitHub issue, or hop onto our [Discord](https://discord.gg/8Tpq4AcN9c) for a quick chat. 159