## 1. Project Overview & Quickstart (amplication/LICENSE) # LICENSE Open-source repository amplication/LICENSE ### Repository Details - **Repository:** [amplication/LICENSE](https://github.com/amplication/LICENSE) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (amplication/docs) ## File: README.md | 📝 **Note** | |------------| | Amplication Documentation moved to https://github.com/amplication/amplication-docs | # Amplication Documentation Welcome to the [Amplication documentation](https://docs.amplication.com/) repository! This repository contains the documentation for the Amplication open-source development platform. Amplication is a low-code development platform that allows developers to quickly build scalable and maintainable applications. The documentation provides detailed information on how to use the platform, including tutorials, guides, and reference material. This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator. ## Installation ```console npm ci ``` ## Local Development ```console npm run start ``` This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. ## Build ```console npm run build ``` This command generates static content into the `build` directory and can be served using any static contents hosting service. ## Deployment ```console GIT_USER= USE_SSH=true npm run deploy ``` If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. # Contributing We welcome contributions to the Amplication documentation! If you find an issue or want to suggest an improvement, please [open a GitHub issue](https://github.com/amplication/amplication/issues/new/choose) and then submit a pull request. --- ## File: docs/concepts/event-driven-architecture.md --- id: event-driven-architecture title: Event-Driven Architecture with Amplication sidebar_label: Event-Driven Architecture slug: /concepts/event-driven-architecture --- # Event-Driven Architecture with Amplication Event-driven architecture is a design pattern that enables loose coupling between microservices. In an event-driven system, services communicate with each other by producing and consuming _events_. This allows for real-time processing and reaction to events. Amplication provides built-in support for event-driven architectures through the use of _message brokers_ and _topics_. By leveraging these features, you can easily build scalable and responsive microservices. :::tip Amplication's [Break The Monolith](/break-the-monolith) feature lets you easily update monolithic architectures into a modern, scalable, and maintainable microservice architecture. ::: ## Key Concepts Before getting started, let's define some important concepts and terms related to event-driven architecture: - **Microservice**: A microservice is a small, independent service that focuses on a single business capability. Microservices are designed to be loosely coupled, allowing them to be developed, deployed, and scaled independently. In an event-driven architecture, microservices communicate with each other through events and message brokers. - **Message Broker**: A message broker is a software component that facilitates communication between services in an event-driven architecture. It receives messages from producers, stores them, and routes them to the appropriate consumers based on predefined rules or subscriptions. - **Topic**: A topic is a named stream or category of events. Producers publish messages to topics, and consumers subscribe to topics to receive messages. Topics provide a logical grouping and enable multiple consumers to independently process events from the same topic. - **Producer**: A producer is a service or component that generates and publishes events to one or more topics. Producers are responsible for creating messages and sending them to the message broker. - **Consumer**: A consumer is a service or component that subscribes to one or more topics and processes the received events. Consumers read messages from the subscribed topics and perform actions based on the content of the messages. ## Enabling Event-Driven Microservices To implement event-driven architecture in your Amplication project, you'll need to: 1. Create a message broker resource 2. Define topics 3. Connect services to the message broker and relevant topics 4. Install a message broker plugin 5. Implement event production and consumption logic :::info For a step-by-step guide on building an event-driven application with Amplication and Kafka, refer to the blog post: [Building Real-time Applications with Amplication and Kafka](https://amplication.com/blog/building-real-time-applications-with-amplication-and-kafka). ::: ## Step 1: Create a Message Broker In your Amplication project, navigate to "Add Resource" and select "[Message Broker](/guides/message-broker)". This will lead you to the Message Broker Creation Wizard. After creating the message broker, you'll be able to configure the settings by installing and configuring the appropriate [message broker plugin](#supported-message-brokers). ## Step 2: Define Topics Create topics that represent the different event categories in your system. Topics act as communication channels between services. They can be created under the "Topics" section of your message broker configuration in Amplication. ## Step 3: Connect Services For each service that needs to interact with the message broker, enable the message broker integration in your service's _Connections_ tab. Specify whether the service should act as a producer or consumer for each relevant topic. ## Step 4: Install Message Broker Plugin Now it's about installing your preferred message broker of choice. Amplication supports using Kafka, MQTT, Redis Message Broker, and various others as your message broker. To find the one most suitable to your project visit the **Plugins** tab and then click on the _Message broker_ category. To use it, install the [message broker plugin](/getting-started/plugins) in each service that will be producing or consuming messages. ## Step 5: Implement Event Production and Consumption In your producer services, add logic to publish events to the appropriate topics when certain actions or conditions occur. Use your chosen message broker client to send messages to the desired topics. In your consumer services, define event handlers that process the messages received from the subscribed topics. You can use decorators like `@EventPattern()` to map event handlers to specific topics and handle incoming messages accordingly. ## Conclusion By leveraging event-driven architecture, you can build microservices that are scalable, responsive, and adaptable to changing requirements. Amplication's built-in support for message brokers and easy integration with various message broker plugins makes it straightforward to implement event-driven communication between your microservices. ## Further Reading For a more detailed walkthrough and practical implementation of event-driven architecture using Amplication and Kafka, be sure to check out the blog post: [Building Real-time Applications with Amplication and Kafka](https://amplication.com/blog/building-real-time-applications-with-amplication-and-kafka). It provides a comprehensive guide on setting up and using event-driven communication in your Amplication projects. --- ## File: docs/community/handling-a-new-issue.md --- id: handling-a-new-issue title: Handling Issues sidebar_label: Handling Issues slug: /community/handling-a-new-issue --- # Handling Issues **This article describes how the Amplication team responds to a new issue in GitHub.** Members of the Amplication community can contribute to the development of Amplication by opening an issue in the [Amplication repository on GitHub](https://github.com/amplication). The issue can be a feature request, a bug report, a documentation update, or a dependency issue. The process described in this document begins after a new issue has been created . The issue will have been added to the **Backlog** project automatically and Maintainers will have received a notification from **Discord** that a new issue has been opened. It is expected that the Contributor will have entered a detailed description of the issue, explaining what problems need to be solved, including any suggestions regarding which steps are required to resolve them. ## Processing a New Issue **A new issue processed in GitHub as follows:** 1. Maintainers change **Backlog** status from **New** to **Baking** and add the appropriate labels. The Issue is validated and researched to gain a deep understanding of the issue. Contributors and Maintainers can add comments and participate in discussions in the GitHub Issue. :::tip **For Internal use only:** If a subject is not relevant for public discussion, the Maintainers can open the issue for an internal discussion in a Discord thread. If a thread is opened on Discord, it should be named according to the following format: **issue-#[]-discussion** (for example, **issue-#2176-discussion**) ::: 2. When the Maintainers have an adequate level of understanding and the issue is ready to be developed, they change **Backlog** status from **Baking** to **Candidate** and apply the appropriate Labels. 3. The Maintainers update the **Status** and **Label** as the project progresses, as described in the [Set Status](#set-status) and [Apply Labels](#apply-labels) sections below. > The **Status Label** must be the same as the project **Status.** Both are set manually. ## Set Status The status indicates to what stage the issue has progressed in the workflow. | Status | Description | Owner | |---|---|---| | New | The issue has been created in GitHub | Maintainers and Contributors | | Baking | Are still researching the issue. Understanding the problem and developing an idea of how the problem can be solved. | Maintainers and Contributors. Typically, a discussion will take place between Contributors and Maintainers in the GitHub Issue where the details will be examined. | | Candidate | Once enough information has been gathered to fully understand the issue, the steps that must be taken to resolve it, and its priority. | Maintainers. Typically, a discussion will take place in the GitHub Issue | | Accepted | A decision has been made that the Candidate is going to be resolved. | Product team | | Scheduled | The issue is added to the roadmap. | Product team | | Closed | The issue has been resolved. | Product team ## **Apply Labels** Applying labels to the issue enables us to categorize and monitor the issue. Labels are metadata that enable us to understand with greater accuracy the nature of the issue. The labels are used, for example, when filtering the list of issues and can be useful in categorizing the contents of the Release Notes. | Label | Mandatory? | Options | |---|---|---| | Type | Mandatory | Dependency, Bug, Feature request, Documentation | | Status | Mandatory | Baking, Candidate, Accepted, Scheduled, Assigned, Wontfix, Duplicate | | Scope | Mandatory| The Scope label follows the following format: **@amplication/[package name]** and indicates which part of Amplication is involved. **Examples:** @amplication/server,@amplication/client, @amplication/cli, @amplication/design-system | | Call to the community | Optional | help wanted, good first issue | ### **Help Wanted** When the issue has the status **Candidate** or **Accepted**, it is possible to add a label **Help wanted.** This indicates that Amplication is not planning to work on the issue at this stage, but members of the community are invited to resolve it. ### Good First Issue This indicates that the issue is suitable for an inexperienced contributor to resolve. ### **Won’t Fix** If it is decided by the Amplication team that the issue will not be fixed, either by Amplication developers or the community, then it is given the status **Wontfix**. In this case, an explanation must be entered to explain the decision. ### **Duplicated Issues** Before closing a duplicated issue, first set the status **duplicate** and write an explanation including the number of the duplicated item. ## What’s Next? When the steps described in this article have been completed the issue is ready for the development phase. --- ## File: docs/api/generated-api-filtering.md --- id: generated-api-filtering title: API Filtering sidebar_label: Generated API - Filtering slug: /api/generated-api-filtering --- # Generated API - Filtering The generated API includes built-in support for filtering, which enables users to specify search criteria for their queries. Filtering is done using the `where` parameter, which defines filters based on record properties or related record properties, such as a user's email address or their top 10 most recent post titles. :::note The `where` parameter can only be used on endpoints and queries that return a list of items, such as `/api/posts` or `/api/posts/{id}/tags`. ::: ## Filter conditions and operators The `where` parameter supports the following operators: - `lt` - `lte` - `gt` - `contains` - `startsWith` - `endsWith` - `mode` - `not` :::note The `Searchable` flag in the entity field settings determines whether a record can be included in a search. This flag is activated by default. ::: To find out more about filters and operators, we recommend reading the [Prisma Client API reference](https://www.prisma.io/docs/reference/api-reference/prisma-client-reference#filter-conditions-and-operators) ## Filtering Examples The following example gets all posts where the title includes the text “Node.js” ### REST API ```jsx curl -X 'GET' \ 'https://[server-url]/api/posts?where%5Btitle%5D[contains]=Node.js' \ -H 'accept: application/json' ``` ### GraphQL ```jsx query{ posts( where:{ title:{ contains:"Node.js" } } ){ id title } } ``` --- ## File: docs/api/generated-api-pagination.md --- id: generated-api-pagination title: API Pagination sidebar_label: Generated API Pagination slug: /api/generated-api-pagination --- # Generated API Pagination The generated API comes with built-in support for Offset pagination. Offset pagination uses the `skip` parameter to exclude the first N items and the `take` parameter to define the number of items to be included on each page. :::note The `skip` and `take` parameters are available only on endpoints and queries that return a list of items. For example: `/api/posts` or `/api/posts/{id}/tags` ::: Pagination requires an implied ordering. This is determined by the `orderBy` parameter. For more information see [Generated API Sorting](../generated-api-sorting) ## Pagination Examples The following examples take items 21-40 from a list of blog posts (equals to 2nd page, in a list with 20 items per page). Skip=20 Take=20 ### REST API ``` curl -X 'GET' \ 'https://[server-url]/api/posts?skip=20&take=20' \ -H 'accept: application/json' ``` ### GraphQL ``` query{ posts( skip:20 take:20 ) { id title } } ``` --- ## File: docs/api/generated-api-sorting.md --- id: generated-api-sorting title: API sorting sidebar_label: Generated API - Sorting slug: /api/generated-api-sorting --- # Generated API - Sorting The generated API comes with built-in support for sorting. Sorting uses the `orderBy` parameter, which accepts an object with the name of the fields. :::note - Amplication does not support sorting by fields of nested entities. - The `orderBy` parameter is available only on endpoints and queries that return a list of items. For example: `/api/posts` or `/api/posts/{id}/tags` ::: ## Sorting Examples The following examples get all posts sorted by the `createdAt` field. ### REST API ```jsx curl -X 'GET' \ 'https://[server-url]/api/posts?orderBy%5BcreatedAt%5D=asc' \ -H 'accept: application/json' ``` ### GraphQL ```jsx query{ posts( orderBy:{ createdAt:desc } ){ id title } } ``` --- ## File: docs/api/index.md --- title: Generated APIs --- # Generated APIs Amplication generates production-ready REST and GraphQL APIs with [Swagger UI](https://swagger.io/tools/swagger-ui/) documentation for all your data models. Easily connect to your data with any HTTP client. ## REST APIs Amplication generates REST APIs that provide you with a way to interact with your data models. Generated APIs include [authentication and authorization](#authentication) and follow strict RESTful conventions. Each generated REST API also comes with **sorting**, **filtering**, and **pagination** features. ### Sorting Retrieve data in a specific order by applying sorting to your API requests. Sort data based on different fields in your data model. ``` GET /api/posts?orderBy[createdAt]=Asc ``` [Learn about sorting](/api/generated-api-sorting/#rest-api) REST API requests. ### Filtering Filter data based on specific criteria by using query parameters in your API requests. Combine multiple filters for more specific results. ``` GET /api/posts?where[title][contains]=Development ``` [Learn about filtering](/api/generated-api-filtering/#rest-api) REST API requests. ### Pagination Paginate API results to manage large datasets and provide a better user experience. Use the `skip` and `take` query parameters to control the number of results per page and the starting point. ``` GET /api/posts?skip=20&take=20 ``` [Learn about paginating](/api/generated-api-pagination/#rest-api) REST API requests. ## GraphQL APIs Besides REST APIs, Amplication also generates GraphQL APIs as an alternative way to help you interact with your data models. GraphQL APIs also support sorting, filtering, pagination, and **meta queries**. ### Sorting Sort the retrieved data in a specific order by adding sorting arguments to your GraphQL queries. Control the sorting order based on fields defined in your data model. ``` query{ posts( orderBy:{ createdAt:Desc } ){ id title } } ``` [Learn about sorting](/api/generated-api-sorting/#graphql) GraphQL API requests. ### Filtering Filter data based on specific criteria by adding filter arguments to your GraphQL queries. Combine multiple filters for more precise results. ``` query{ posts( where:{ title:{ contains:"Development" } } ){ id title } } ``` [Learn about filtering](/api/generated-api-filtering/#graphql) GraphQL API requests. ### Pagination Implement pagination in your GraphQL queries to handle large datasets and improve the user experience. Use the `skip` and `take` arguments to control the number of results and the starting point. ``` query{ posts( skip:20 take:20 ) { id title } } ``` [Learn about paginating](/api/generated-api-pagination/#graphql) GraphQL API requests. ### Meta Queries Use meta queries to gather additional information about your data, such as the total number of records or the aggregation of certain fields. ``` query{ _customersMeta(where:{ firstName:{ contains:"jack" } }){ count } } ``` [Learn more about meta queries](/api/meta-query-graphql/) with your GraphQL API requests. ## Authentication Amplication generates authentication mechanisms based on the NestJS/Passport library. It supports various authentication mechanisms like JWT-based authentication and custom authentication with Passport. [Learn more about authorizing](/authentication/) your API requests. --- ## File: docs/api/metaquery-graphql.md --- id: meta-query-graphql title: GraphQL Meta Queries sidebar_label: GraphQL Meta Queries slug: /api/meta-query-graphql --- # Meta Query in GraphQL ## Obtaining the record count of a query You can use the `_EntitiesMeta API` to obtain the total record count of a query. The meta query supports all the parameters that are supported in the `FindMany` query. ```bash query{ _customersMeta(where:{ firstName:{ contains:"jack" } }){ count } } ``` This will return a JSON object with a single property: `count`, which represents the total number of records that match the query. ## Obtaining the result count of a query You can also use the meta query together with the `findMany` query to obtain the result count for a specific query. ```bash query customers($where: CustomerWhereInput, $orderBy: CustomerOrderByInput, $skip: Float, $take: Float) { items: customers(where: $where, orderBy: $orderBy, skip: $skip, take: $take) { id createdAt updatedAt firstName lastName __typename } total: _customersMeta(where: $where, orderBy: $orderBy, skip: $skip, take: $take) { count __typename } } ``` This query will return two objects: `items` and `total`. The `items` object contains an array of records that match the specified criteria, while the `total` object contains the total number of records that match the query, as determined by the `_customersMeta` meta query. --- ## File: docs/about/index.md --- title: About Amplication --- # About Amplication Amplication is a backend development platform that simplifies and accelerates the process of creating and evolving scalable backend services by auto-generating production-ready code. With support for both Node.js and .NET, Amplication provides developers with the flexibility to select the best technology stack for their needs. ## Open Source and Commercial Offerings Amplication offers both open-source and commercial solutions for backend service generation. The free version of our Node.js application generation tools is available as open-source software, allowing developers to freely access, modify, and distribute the source code. In addition, Amplication provides a premium Enterprise plan for its Node.js tools with additional features and support. The .NET solution offered by Amplication is part of the Enterprise plan. For more information regarding the licensing details, please visit our [licensing model](/about/licensing) page. ## How Amplication can help you Our main goal is to help developers build and evolve Node.js and .NET apps faster and more efficiently. To help you do that, here are some of the features that Amplication offers: - [**Generate Human-Readable Code**](/getting-started/): Amplication automatically generates fully functional, human-readable, and editable services. This includes applications based on TypeScript and Node.js, as well as robust and scalable applications based on .NET. - [**Sync With Git Provider**](/sync-with-github/): As you make changes to your application using Amplication's visual builders and CLI, the platform automatically syncs those modifications to your git repository. - [**Automatic API Generation**](/api/): Automatically generate fully functional REST and GraphQL APIs based on your data models. - **And more...** :::note [Get started](/) or visit [our GitHub](https://github.com/amplication/) to see what's possible and all the other features we offer. ::: ## Meet The Amplication Team Amplication is a small, dedicated team, revolutionizing the speed and ease of cloud development. Our mission is to simplify application development, unlock frictionless developer experience and bring best practices to any developer in any organization. We believe this approach will shape the next-generation programming. [Meet our team](https://amplication.com/team). ## We're Here To Help We've answered your primary questions in our [FAQs](/faqs/). If you still have questions, we're here to help. [Contact us](https://amplication.com/contact-us) to speak with our customer success manager or get technical support. We look forward to talking with you soon. --- ## File: docs/about/licensing.md --- id: licensing title: Amplication's licensing model sidebar_label: Amplication's licensing model slug: /about/licensing --- # Amplication's Licensing Model Amplication offers both open-source and commercial licensing options to accommodate the needs of various users — from individual developers to large enterprises. ## Open Source and Enterprise Offerings ### Free Edition - The Free Edition of Amplication includes our core functionality, based on Node.js. This edition is available under the [Apache 2.0 license](https://github.com/amplication/amplication/blob/master/LICENSE) and remains free for use on our managed service at [amplication.com](https://amplication.com). - Developers can freely access, modify, and distribute the source code available in this edition, fostering a collaborative and open development environment. ### Enterprise Edition - The Enterprise Edition extends the Node.js Free Edition by incorporating advanced operational and security features. This edition also introduces support for .NET applications, offering robust, scalable backend solutions. - This premium tier is designed for businesses seeking enhanced features like advanced data handling and API capabilities, architecture management, increased automation, and comprehensive support for both Node.js and .NET applications. - The Enterprise Edition is partly open-source, partly source available, and partly Amplication proprietary and not source-available. The idea is to keep the Amplication business while doing the maximum for the community and our loved developers. ## Amplication's Commitment to Open Source Amplication remains deeply committed to the open-source community. As we expand our offerings with the Enterprise Edition, we make sure to align our development practices and commercial solutions with the values of our open-source projects.