appwrite/src/Appwrite/Platform/AGENTS.md

Modules AGENTS.md

Before reading this file, also read Appwrite's base AGENTS.md.

Modules are the building blocks of the Appwrite platform. They are responsible for handling specific tasks, defining background workers, and providing API endpoints. Each module should have its own directory within the src/Appwrite/Platform/Modules directory.

Generally-speaking, each service is its own module, but there are some exceptions. The goal is to always put related code that achieves a specific goal under one roof.

Structure and Naming Conventions

When adding a module, always add a new directory under src/Appwrite/Platform/Modules. The directory name should be PascalCase, and if possible, use only one word. For example, User, Database, Storage, etc. Avoid using shorthands, unless they are standardized, such as DB, JWT, or SMTP.

A module consists of:

• Module.php - Simple register class registering all module's services (from Services directory)
• Workers directory - Contains behavior for module-specific workers
• Tasks directory - Contains behavior for module-specific CLI tasks
• Http directory - Contains HTTP endpoints for the module
• Services directory - Contains register classes for all relevant types of services

Inside module, the Services directory can contain:

• Http.php - Register HTTP endpoints and hooks from Http directory
• Workers.php - Register workers from Workers directory
• Tasks.php - Register CLI tasks from Tasks directory

After implementing a module, make sure to register it in src/Appwrite/Platform/Appwrite.php.

HTTP directory structure

Inside module's Http directory, there are multiple rules to follow:

1. Directly in Http directory, there should only be directories for services (and hooks, check point number 2). If a module is a single service, it's okay to only have one directory, with the same name as the service, for example src/Appwrite/Platform/Modules/Account/Http/Account. An example with multiple services is src/Appwrite/Platform/Modules/Databases/Http/Databases and src/Appwrite/Platform/Modules/Databases/Http/TablesDB.

2. Hooks should live in Hooks directory, under Init, Shutdown, or Error directories, inside Http directory. For example, an init hook to prevent unauthorized access might live in src/Appwrite/Platform/Modules/Functions/Http/Hooks/Init/Authentication.php.

3. Inside Http directories for services, file names can only be Get.php, Update.php, Create.php, Delete.php or XList.php. We call it XList, because List is a reserved keyword and PHP would not like that. Never use any other words! Let's say you want a method to be blockUser, tempting to add Users/Block.php, instead, think of the resource and property it affects. Better naming would be Users/Status/Update.php (update user's status). Doing so also nicely reflects in the HTTP endpoint, PATCH /v1/users/:userId/status.

4. It's allowed to nest directories in Http service directories. For example, if you want to create a new deployment for a function based on a template, an endpoint might live in src/Appwrite/Platform/Modules/Functions/Http/Functions/Deployments/Template/Create.php. In this example, notice functions and deployments are resources, and template is property - both resources and properties can be nested, and have separate directories.

Sample module directory structure

src/Appwrite/Platform/Modules/Functions
├── Module.php
├── Workers
│   └── Builds.php
├── Tasks
│   └── Block.php
├── Http
│   └── Functions
│       ├── Create.php
│       ├── XList.php
│       ├── Update.php
│       ├── Delete.php
│       ├── Get.php
│       └── Deployments
│           ├── XList.php
│           ├── Delete.php
│           ├── Get.php
│           └── Template
│               └── Create.php
└── Services
    ├── Http.php
    ├── Workers.php
    └── Tasks.php