strapi/docs/3.x.x/en/concepts/concepts.md

Concepts

• Table of contents
  • Files structure
  • Controllers
  • Filters
  • Models
    • Attributes
    • Relations
      • Many-to-many
      • One-to-many
      • One-to-one
      • One-way
    • Lifecycle callbacks
  • Internationalization
  • Plugin
  • Plugin styles
  • Policies
    • Global policies
    • Scoped policies
    • Plugin policies
  • Public assets
  • Requests
  • Responses
  • Routing
  • Services

---

Files structure

By default, your project's structure will look like this:

• /admin: contains the vast majority of the admin's front-end and back-end logic.
• /api: contains the business logic of your project will be in this folder split in sub-folder per API.
  • **
    • /config: contains the API's configurations (routes, policies, etc).
    • /controllers: contains the API's controllers.
    • /models: contains the API's models.
    • /services: contains the API's services.
• /node_modules: contains the npm's packages used by the project.
• /config
  • /environments: contains the project's configurations per environment.
    • /**
      • /development
        • custom.json: contains the custom configurations for this environment.
        • database.json: contains the database connections for this environment.
        • request.json: contains the request settings for this environment.
        • response.json: contains the response settings for this environment.
        • server.json: contains the server settings for this environment.
      • /production
      • /staging
  • /functions: contains lifecycle or generic functions of the project.
  • /locales: contains the translation files used by the built-in i18n feature.
  • application.json: contains the general configurations of the project.
  • custom.json: contains the custom configurations of the project.
  • hook.json: contains the hook settings of the project.
  • language.json: contains the language settings of the project.
  • middleware.json: contains the middleware settings of the project.
• /hooks: contains the custom hooks of the project.
• /middlewares: contains the custom middlewares of the project.
• /plugins: contains the installed plugins in the project.
• /public: contains the file accessible to the outside world.

Tips: Inside the /config folder, every folder will be parsed and injected into the global object strapi.config. Let's say, you added a folder named credentials with two files stripe.json and paypal.json into it. The content of these files will be accessible through strapi.config.credentials.stripe and strapi.config.credentials.paypal.

---

Controllers

Controllers are JavaScript files which contain a set of methods called actions reached by the client according to the requested route. It means that every time a client requests the route, the action performs the business logic coded and sends back the response. They represent the C in the MVC pattern. In most cases, the controllers will contain the bulk of a project's business logic.

module.exports = {
  // GET /hello
  index: async (ctx) => {
    ctx.send('Hello World!');
  }
};

In this example, any time a web browser is pointed to the /hello URL on your app, the page will display the text: Hello World!.

Where are the controllers defined?

The controllers are defined in each ./api/**/controllers/ folders. Every JavaScript file put in these folders will be loaded as a controller. They are also available through the strapi.controllers and strapi.api.**.controllers global variables. By convention, controllers' names should be Pascal-cased, so that every word in the file (include the first one) is capitalized User.js, LegalEntity.js.

Please refer to the controllers' guide for more informations.

---

Filters

Filters are a handy way to request data according to generic parameters. It makes filtering, sorting and paginating easy and reusable (eg. GET /user?_limit=30&name=John).

Please refer to the filters' guide for more informations.

---

Models

Models are a representation of the database's structure and lifecyle. They are split into two separate files. A JavaScript file that contains the lifecycle callbacks, and a JSON one that represents the data stored in the database and their format. The models also allow you to define the relationships between them.

Path — ./api/user/models/User.js.

module.exports = {
  // Before saving a value.
  // Fired before an `insert` or `update` query.
  beforeSave: (next) => {
    // Use `this` to get your current object
    next();
  },

  // After saving a value.
  // Fired after an `insert` or `update` query.
  afterSave: (doc, next) => {
    next();
  },

  // ... and more
};

Path — ./api/user/models/User.settings.json.

{
  "connection": "default",
  "info": {
    "name": "user",
    "description": "This represents the User Model"
  },
  "attributes": {
    "firstname": {
      "type": "string"
    },
    "lastname": {
      "type": "string"
    }
  }
}

In this example, there is a User model which contains two attributes firstname and lastname.

Where are the models defined?

The models are defined in each ./api/**/models/ folder. Every JavaScript or JSON file in these folders will be loaded as a model. They are also available through the strapi.models and strapi.api.**.models global variables. Usable every where in the project, they contain the ORM model object that they are refer to. By convention, models' names should be Pascal-cased, so that every word in the file (including the first one) is capitalized User.js, User.settings.json, LegalEntity.js, LegalEntity.settings.json.

Attributes

A model must contain a list of attributes, and each of these attributes must have a type.

Please refer to the models' guide for more informations about the attributes.

Relations

Many-to-many

Many-to-many associations allow to link an entry to many entry.

Please refer to the many-to-many guide

One-to-many

One-way relationships are useful to link an entry to another.

Please refer to the one-to-many guide

One-to-one

One-way relationships are useful to link an entry to another.

Please refer to the one-to-one guide.

One-way

One-way relationships are useful to link an entry to another. However, only one of the models can be queried with its populated items.

Please refer to the one-way guide.

Lifecycle callbacks

Lifecycle callbacks are functions triggered at specific moments of the queries.

Please refer to the lifecycle callbacks guide.

---

Internationalization and localization

Internationalization and localization (i18n) allows to adapt the project to different languages and serve the right content to the users. This feature is deeply integrated into the Strapi's core. It will detect the user language preference (locale) and translate the requested content using the translation files.

Please refer to the internationalization's guide.

---

Plugin

A plugin is like a fully independent sub-application. It has its own business logic with dedicated models, controllers, services, middlewares or hooks. It can also contain an UI integrated into the admin panel to use it easily. It allows to develop or plugin features in a project in a short time span.

Please refer to the plugins documentation for more informations.

---

Plugin styles

The admin panel uses Bootstrap to be styled on top of solid conventions and reusable CSS classes. It is also using PostCSS and PostCSS SCSS to keep the code maintainable.

Please refer to the plugin front-end development for detailed informations.

---

Policies

Policies are functions which have the ability to execute specific logic on each request before it reaches the controller's action. They are mostly used for securing business logic easily. Each route of the project can be associated to an array of policies. For example, you can create a policy named isAdmin, which obviously checks that the request is sent by an admin user, and use it for critical routes.

Policies can be:

• global: so they can be used within the entire project.
• scoped: used by single API or plugin.

Where are the policies defined?

The API and plugins policies (scoped) are defined in each ./api/**/config/policies/ folders and plugins. They are respectively exposed through strapi.api.**.config.policies and strapi.plugins.**.config.policies. The global policies are defined at ./config/policies/ and accessible via strapi.config.policies.

Please refer to the policy guide

Global policies

Global policies are reusable through the entire app.

Please refer to the global policy guide

Scoped policies

A policy defined in an API or plugin is usable only from this API or plugin. You don't need any prefix to use it.

Please refer to the scoped policy guide.

Plugin policies

Plugin policies are usable from any app API.

Please refer to the plugin policy guide.

Public Assets

Public assets are static files such as images, video, css, etc that you want to make accessible to the outside world. Every new project includes by default, a folder named ./public.

Please refer to the public configuration for more informations.

---

Requests

The context object (ctx) contains all the request's related informations.

Please refer to the requests guide for more informations.

---

Responses

The context object (ctx) contains a list of values and functions useful to manage server responses.

Please refer to the responses guide for more informations.

---

Routing

./api/**/config/routes.json files define all available routes for the clients.

Please refer to the routing guide for more informations.

---

Services

Services are a set of reusable functions. They are particularly useful to respect the DRY (don’t repeat yourself) programming concept and to simplify controllers logic.

Please refer to the services guide for more informations.

---