Concepts 

Models 

A Model in Gadget represents a table in the underlying PostgreSQL database, and it serves as the foundation for creating and organizing your application's data. Each Model consists of a set of fields with specific data types and optional validations, which together define the shape and rules for the data stored within that Model. When you create a Model, Gadget automatically generates a GraphQL API for your application, enabling you to perform CRUD (Create, Read, Update, and Delete) operations on your Models.

Actions 

An Action is a unit of work that your application can perform, defining the behavior of the application. They work as serverless functions with a defined framework eliminating the boilerplate code that developers commonly set up (event processing, authorization, etc) and respond to various triggers, such as user interactions, API calls, or webhooks from external systems. Actions help developers streamline their applications by handling custom logic like input validation, record updates, third-party API interactions, and more.

Action Framework 

The Gadget framework for an Action can be broken down into 3 steps:

1. Triggers - An Action occurs when:

Actions are initiated by a Trigger. Triggers can be GraphQL API mutations, webhooks from third-party services, or scheduled events. Triggers define when an Action should be executed.

2. Permissions - Before an Action is executed:

Gadget checks if the current user or API key has the necessary permissions & settings enabled to perform the Action. Permissions determine who can run an Action.

3. Effects - When an Action executes what happens?:

Once an Action executes it performs certain effects. Effects are the building blocks of Actions that define the custom logic and operations to be executed when an Action is triggered. They are the "what" of an Action, dictating the tasks to be performed, such as record manipulation, API calls, or data logging.

Model Actions 

Model Actions are Actions that run in the context of specific records. These Actions are ideal for operations that involve particular records within a Gadget Model.

To determine whether to use a Model Action, ask the question, "Does this Action operate on a specific record of a specific Model?". For example in a project management app, a Model Action 'markAsComplete' on a 'task' Model could be used. This action updates a specific task record's status to 'completed' when a team member finishes their assigned task, providing real-time updates to the project's progress.

Global Actions 

Global Actions are Actions that run outside the context of any particular record. These Actions are used for scenarios that don't involve specific records but still require the Gadget framework's support.

To decide if a Global Action is appropriate, consider if the Action doesn't read or write data to or from a specific central record. For example in a project management app, a Global Action like 'dailyStatusUpdate' could be used to summarize the day's completed tasks and upcoming deadlines from all projects, then send a report to all team members. This doesn't interact with a specific project or 'task' record, but fetches and processes data from multiple records across the application.

HTTP Routes 

HTTP Routes are true serverless routes in Gadget. They're used as an alternative solution to Actions in situations where developers need to handle custom requests or scenarios that fall outside the scope provided by the standard Action framework (sending JSON responses, handling webhooks from connections not provided by Gadget, or dynamically generating files). They consist of a URL pattern and a handler function that executes when someone accesses the specified URL on the app's domain and can be found within HTTP routes in Gadget are defined as files in the routes folder, each route has a specific filename which determines the URL path the route.

For example, if you wanted to send an SMS every time a Shopify Product is created in a store, you would use a Model Action because Gadget has a connection that handles triggers for Shopify's webhooks. But if you wanted to send an SMS when Stripe sends a webhook, a connection for which we do not yet have a trigger you would use an HTTP route.