# Appwrite Plugin Design - Phase I
> **MCP Plugin برای مدیریت Appwrite Self-Hosted روی Coolify**
**Version**: v1.0.0 (طراحی)
**Priority**: High (جایگزین Phase J)
**Estimated Tools**: 85-95
---
## Overview
پلاگین Appwrite برای مدیریت **Appwrite Self-Hosted** روی Coolify طراحی شده است. Appwrite یک پلتفرم Backend-as-a-Service متنباز است که امکانات جامعی برای Database، Authentication، Storage، Functions و Messaging ارائه میدهد.
### مقایسه با Supabase
```
┌─────────────────────────────────────────────────────────────────┐
│ Appwrite vs Supabase Self-Hosted │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Appwrite: │
│ ├── Document-based Database (NoSQL-like) │
│ ├── Built-in Users & Teams management │
│ ├── Messaging (Email, SMS, Push) built-in │
│ ├── 30+ OAuth providers │
│ ├── Multi-runtime Functions (Node, Python, PHP, etc.) │
│ ├── Database Transactions (v1.8+) │
│ └── GraphQL + REST APIs │
│ │
│ Supabase: │
│ ├── PostgreSQL (relational) │
│ ├── GoTrue for Auth │
│ ├── No built-in messaging │
│ ├── Deno-only Edge Functions │
│ └── PostgREST for REST API │
│ │
│ هر دو: Self-Hosted، Open Source، Coolify-compatible │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### ویژگیهای Self-Hosted Appwrite
```
✅ موجود در Self-Hosted:
├── Database API (Collections, Documents, Queries)
├── Users API (Users, Sessions, Teams, Memberships)
├── Storage API (Buckets, Files, Image Transformation)
├── Functions API (Deployments, Executions, Variables)
├── Messaging API (Email, SMS, Push Notifications)
├── Health API (Service status, Queue monitoring)
├── Avatars API (Image utilities)
├── Realtime API (WebSocket subscriptions)
├── GraphQL API (Alternative to REST)
└── Webhooks & Events
❌ محدودیتها:
├── Console API (Project management) - نیاز به Console access
├── Rate limiting بالا (پیشفرض 60/دقیقه) - قابل تنظیم
└── بعضی features نیاز به تنظیمات اضافی دارند
```
---
## Authentication
### روشهای احراز هویت
```
┌─────────────────────────────────────────────────────────────────┐
│ Appwrite Self-Hosted Authentication │
├─────────────────────────────────────────────────────────────────┤
│ │
│ API Key: │
│ ├── X-Appwrite-Key header │
│ ├── Server-side only │
│ ├── Scoped permissions │
│ ├── Bypasses rate limits │
│ └── Admin mode (bypasses permissions) │
│ │
│ JWT Token: │
│ ├── Authorization: Bearer {token} │
│ ├── 15-minute expiration │
│ ├── Respects user permissions │
│ └── Rate limited (10 tokens/60min/user) │
│ │
│ Session (Client): │
│ ├── Cookie-based │
│ ├── For client SDKs │
│ └── Subject to rate limiting │
│ │
│ Project ID: │
│ ├── X-Appwrite-Project header (required) │
│ └── Identifies which project to access │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### Environment Variables
```bash
# Appwrite Self-Hosted Instance (Required)
APPWRITE_SITE1_URL=https://appwrite.example.com/v1
APPWRITE_SITE1_PROJECT_ID=your-project-id
APPWRITE_SITE1_API_KEY=your-api-key-with-scopes
APPWRITE_SITE1_ALIAS=myappwrite
# Multiple Instances
APPWRITE_SITE2_URL=https://appwrite-staging.example.com/v1
APPWRITE_SITE2_PROJECT_ID=staging-project-id
APPWRITE_SITE2_API_KEY=staging-api-key
APPWRITE_SITE2_ALIAS=staging
```
### API Key Scopes
```
Authentication & Users:
├── sessions.read / sessions.write
├── users.read / users.write
└── teams.read / teams.write
Database:
├── databases.read / databases.write
├── collections.read / collections.write (tables)
├── attributes.read / attributes.write (columns)
├── indexes.read / indexes.write
└── documents.read / documents.write (rows)
Storage:
├── buckets.read / buckets.write
└── files.read / files.write
Functions:
├── functions.read / functions.write
└── execution.read / execution.write
Messaging:
├── messages.read / messages.write
├── providers.read / providers.write
├── topics.read / topics.write
└── subscribers.read / subscribers.write
Other:
├── health.read
├── locale.read
└── avatars.read
```
---
## API Endpoints
### Base URL Structure
```
Self-Hosted: https://[SERVER_HOSTNAME]/v1
Database:
GET/POST /databases
GET/PUT/DELETE /databases/{databaseId}
GET/POST /databases/{databaseId}/collections
GET/POST /databases/{databaseId}/collections/{collectionId}/documents
...
Users:
GET/POST /users
GET/PUT/DELETE /users/{userId}
GET/DELETE /users/{userId}/sessions
...
Storage:
GET/POST /storage/buckets
GET/POST /storage/buckets/{bucketId}/files
GET /storage/buckets/{bucketId}/files/{fileId}/preview
...
Functions:
GET/POST /functions
POST /functions/{functionId}/executions
...
Messaging:
GET/POST /messaging/providers
GET/POST /messaging/topics
POST /messaging/messages
...
Health:
GET /health
GET /health/db
GET /health/queue
...
```
---
## Architecture
### Project Structure
```
plugins/appwrite/
├── __init__.py # Export: AppwritePlugin, AppwriteClient
├── plugin.py # کلاس اصلی AppwritePlugin
├── client.py # AppwriteClient (REST client)
└── handlers/
├── __init__.py
├── databases.py # Database & Collections (18 tools)
├── documents.py # Document CRUD & Queries (12 tools)
├── users.py # User management (12 tools)
├── teams.py # Teams & Memberships (10 tools)
├── storage.py # Buckets & Files (14 tools)
├── functions.py # Functions & Executions (14 tools)
├── messaging.py # Email, SMS, Push (12 tools)
└── system.py # Health & Avatars (8 tools)
```
### Client Architecture
```python
class AppwriteClient:
"""
REST API Client for Appwrite Self-Hosted
All requests include Project ID and API Key headers.
"""
def __init__(
self,
base_url: str, # e.g., https://appwrite.example.com/v1
project_id: str, # Appwrite project ID
api_key: str, # API key with required scopes
):
self.base_url = base_url.rstrip('/')
self.project_id = project_id
self.api_key = api_key
def _get_headers(self, additional_headers: Optional[Dict] = None) -> Dict[str, str]:
"""Get request headers with authentication."""
headers = {
"Content-Type": "application/json",
"X-Appwrite-Project": self.project_id,
"X-Appwrite-Key": self.api_key,
}
if additional_headers:
headers.update(additional_headers)
return headers
async def request(
self,
method: str,
endpoint: str,
params: Optional[Dict] = None,
json_data: Optional[Dict] = None,
headers_override: Optional[Dict] = None
) -> Any:
"""Make authenticated request to Appwrite API"""
url = f"{self.base_url}{endpoint}"
headers = self._get_headers(headers_override)
# ... request logic
```
---
## Tool Categories
### 1. Databases Handler (18 tools)
مدیریت Databases و Collections
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_databases` | GET | read | لیست databases |
| `get_database` | GET | read | جزئیات database |
| `create_database` | POST | write | ایجاد database |
| `update_database` | PUT | write | بهروزرسانی database |
| `delete_database` | DELETE | admin | حذف database |
| `list_collections` | GET | read | لیست collections |
| `get_collection` | GET | read | جزئیات collection |
| `create_collection` | POST | write | ایجاد collection |
| `update_collection` | PUT | write | بهروزرسانی collection |
| `delete_collection` | DELETE | admin | حذف collection |
| `list_attributes` | GET | read | لیست attributes |
| `create_string_attribute` | POST | write | attribute متنی |
| `create_integer_attribute` | POST | write | attribute عددی |
| `create_boolean_attribute` | POST | write | attribute boolean |
| `create_enum_attribute` | POST | write | attribute enum |
| `create_datetime_attribute` | POST | write | attribute تاریخ |
| `delete_attribute` | DELETE | admin | حذف attribute |
| `list_indexes` | GET | read | لیست indexes |
| `create_index` | POST | write | ایجاد index |
| `delete_index` | DELETE | admin | حذف index |
```python
# Create Collection Example
{
"name": "create_collection",
"method_name": "create_collection",
"description": "Create a new collection in database",
"schema": {
"type": "object",
"properties": {
"database_id": {
"type": "string",
"description": "Database ID"
},
"collection_id": {
"type": "string",
"description": "Unique collection ID (use 'unique()' for auto)"
},
"name": {
"type": "string",
"description": "Collection name"
},
"permissions": {
"type": "array",
"items": {"type": "string"},
"description": "Array of permission strings",
"default": []
},
"document_security": {
"type": "boolean",
"description": "Enable document-level permissions",
"default": true
},
"enabled": {
"type": "boolean",
"default": true
}
},
"required": ["database_id", "collection_id", "name"]
},
"scope": "write"
}
```
### 2. Documents Handler (12 tools)
عملیات CRUD روی Documents
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_documents` | GET | read | لیست documents با فیلتر |
| `get_document` | GET | read | دریافت یک document |
| `create_document` | POST | write | ایجاد document |
| `update_document` | PATCH | write | بهروزرسانی document |
| `delete_document` | DELETE | write | حذف document |
| `bulk_create_documents` | POST | write | ایجاد دستهای |
| `bulk_update_documents` | PATCH | write | بهروزرسانی دستهای |
| `bulk_delete_documents` | DELETE | write | حذف دستهای |
| `count_documents` | GET | read | شمارش documents |
| `search_documents` | GET | read | جستجوی full-text |
| `create_transaction` | POST | admin | شروع transaction (v1.8+) |
| `commit_transaction` | PUT | admin | commit/rollback transaction |
```python
# List Documents with Queries
{
"name": "list_documents",
"method_name": "list_documents",
"description": "List documents with queries, filters, and pagination",
"schema": {
"type": "object",
"properties": {
"database_id": {
"type": "string",
"description": "Database ID"
},
"collection_id": {
"type": "string",
"description": "Collection ID"
},
"queries": {
"type": "array",
"items": {"type": "string"},
"description": "Query strings (e.g., 'equal(\"status\", \"active\")')",
"examples": [
"equal(\"status\", [\"active\"])",
"greaterThan(\"price\", 100)",
"search(\"title\", \"keyword\")",
"orderDesc(\"createdAt\")",
"limit(25)",
"offset(0)"
]
}
},
"required": ["database_id", "collection_id"]
},
"scope": "read"
}
```
### 3. Users Handler (12 tools)
مدیریت کاربران
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_users` | GET | read | لیست کاربران |
| `get_user` | GET | read | جزئیات کاربر |
| `create_user` | POST | write | ایجاد کاربر |
| `update_user` | PATCH | write | بهروزرسانی کاربر |
| `delete_user` | DELETE | admin | حذف کاربر |
| `update_user_email` | PATCH | write | تغییر ایمیل |
| `update_user_phone` | PATCH | write | تغییر تلفن |
| `update_user_status` | PATCH | admin | فعال/غیرفعال کردن |
| `update_user_labels` | PUT | admin | تنظیم labels |
| `list_user_sessions` | GET | read | لیست sessions |
| `delete_user_sessions` | DELETE | admin | حذف همه sessions |
| `delete_user_session` | DELETE | admin | حذف یک session |
```python
# Create User Example
{
"name": "create_user",
"method_name": "create_user",
"description": "Create a new user",
"schema": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "Unique user ID (use 'unique()' for auto)"
},
"email": {
"type": "string",
"format": "email",
"description": "User email"
},
"phone": {
"type": "string",
"description": "Phone number (E.164 format)"
},
"password": {
"type": "string",
"minLength": 8,
"description": "Password (min 8 chars)"
},
"name": {
"type": "string",
"description": "User display name"
}
},
"required": ["user_id"]
},
"scope": "write"
}
```
### 4. Teams Handler (10 tools)
مدیریت Teams و Memberships
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_teams` | GET | read | لیست teams |
| `get_team` | GET | read | جزئیات team |
| `create_team` | POST | write | ایجاد team |
| `update_team` | PUT | write | بهروزرسانی team |
| `delete_team` | DELETE | admin | حذف team |
| `list_team_memberships` | GET | read | لیست اعضا |
| `create_team_membership` | POST | write | دعوت عضو |
| `update_membership` | PATCH | write | بهروزرسانی عضویت |
| `delete_membership` | DELETE | write | حذف عضو |
| `update_membership_status` | PATCH | write | تایید/رد عضویت |
### 5. Storage Handler (14 tools)
مدیریت Buckets و Files
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_buckets` | GET | read | لیست buckets |
| `get_bucket` | GET | read | جزئیات bucket |
| `create_bucket` | POST | write | ایجاد bucket |
| `update_bucket` | PUT | write | بهروزرسانی bucket |
| `delete_bucket` | DELETE | admin | حذف bucket |
| `list_files` | GET | read | لیست فایلها |
| `get_file` | GET | read | جزئیات فایل |
| `create_file` | POST | write | آپلود فایل |
| `update_file` | PUT | write | بهروزرسانی فایل |
| `delete_file` | DELETE | write | حذف فایل |
| `get_file_download` | GET | read | دانلود فایل |
| `get_file_preview` | GET | read | پیشنمایش تصویر |
| `get_file_view` | GET | read | مشاهده در browser |
| `move_file` | PUT | write | انتقال فایل |
```python
# Get File Preview with Transformations
{
"name": "get_file_preview",
"method_name": "get_file_preview",
"description": "Get image preview with transformations",
"schema": {
"type": "object",
"properties": {
"bucket_id": {"type": "string"},
"file_id": {"type": "string"},
"width": {
"type": "integer",
"minimum": 0,
"maximum": 4000,
"description": "Preview width (0-4000)"
},
"height": {
"type": "integer",
"minimum": 0,
"maximum": 4000,
"description": "Preview height (0-4000)"
},
"gravity": {
"type": "string",
"enum": ["center", "top", "top-left", "top-right",
"left", "right", "bottom", "bottom-left", "bottom-right"],
"default": "center"
},
"quality": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"default": 90
},
"output": {
"type": "string",
"enum": ["jpeg", "jpg", "png", "gif", "webp", "avif"],
"default": "webp"
},
"rotation": {
"type": "integer",
"minimum": 0,
"maximum": 360
},
"background": {
"type": "string",
"description": "Background color (hex without #)"
},
"border_width": {"type": "integer"},
"border_color": {"type": "string"},
"border_radius": {"type": "integer"}
},
"required": ["bucket_id", "file_id"]
},
"scope": "read"
}
```
### 6. Functions Handler (14 tools)
مدیریت Serverless Functions
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_functions` | GET | read | لیست functions |
| `get_function` | GET | read | جزئیات function |
| `create_function` | POST | write | ایجاد function |
| `update_function` | PUT | write | بهروزرسانی function |
| `delete_function` | DELETE | admin | حذف function |
| `list_deployments` | GET | read | لیست deployments |
| `get_deployment` | GET | read | جزئیات deployment |
| `create_deployment` | POST | write | deploy کد جدید |
| `delete_deployment` | DELETE | write | حذف deployment |
| `update_deployment` | PATCH | write | فعال کردن deployment |
| `list_executions` | GET | read | لیست executions |
| `get_execution` | GET | read | جزئیات execution |
| `create_execution` | POST | write | اجرای function |
| `delete_execution` | DELETE | write | حذف execution log |
```python
# Create Execution (Run Function)
{
"name": "create_execution",
"method_name": "create_execution",
"description": "Execute a function",
"schema": {
"type": "object",
"properties": {
"function_id": {
"type": "string",
"description": "Function ID"
},
"body": {
"type": "string",
"description": "Request body (string or JSON string)"
},
"async": {
"type": "boolean",
"default": false,
"description": "Run asynchronously"
},
"path": {
"type": "string",
"description": "Custom execution path"
},
"method": {
"type": "string",
"enum": ["GET", "POST", "PUT", "PATCH", "DELETE"],
"default": "POST"
},
"headers": {
"type": "object",
"description": "Custom headers"
}
},
"required": ["function_id"]
},
"scope": "write"
}
```
### 7. Messaging Handler (12 tools)
ارسال پیام از طریق Email, SMS, Push
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_providers` | GET | read | لیست providers |
| `get_provider` | GET | read | جزئیات provider |
| `create_email_provider` | POST | admin | ایجاد email provider |
| `create_sms_provider` | POST | admin | ایجاد SMS provider |
| `create_push_provider` | POST | admin | ایجاد push provider |
| `delete_provider` | DELETE | admin | حذف provider |
| `list_topics` | GET | read | لیست topics |
| `create_topic` | POST | write | ایجاد topic |
| `delete_topic` | DELETE | write | حذف topic |
| `create_subscriber` | POST | write | اضافه کردن subscriber |
| `delete_subscriber` | DELETE | write | حذف subscriber |
| `send_message` | POST | write | ارسال پیام |
```python
# Send Email Message
{
"name": "send_message",
"method_name": "send_message",
"description": "Send email, SMS, or push notification",
"schema": {
"type": "object",
"properties": {
"message_id": {
"type": "string",
"description": "Unique message ID"
},
"type": {
"type": "string",
"enum": ["email", "sms", "push"],
"description": "Message type"
},
"topics": {
"type": "array",
"items": {"type": "string"},
"description": "Target topic IDs"
},
"targets": {
"type": "array",
"items": {"type": "string"},
"description": "Target user IDs"
},
"subject": {
"type": "string",
"description": "Email subject"
},
"content": {
"type": "string",
"description": "Message content (HTML for email)"
},
"scheduled_at": {
"type": "string",
"format": "date-time",
"description": "Schedule delivery time"
}
},
"required": ["message_id", "type", "content"]
},
"scope": "write"
}
```
### 8. System Handler (8 tools)
سلامت سیستم و Utilities
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `health_check` | GET | read | وضعیت کلی سرور |
| `health_db` | GET | read | وضعیت database |
| `health_cache` | GET | read | وضعیت cache |
| `health_queue` | GET | read | وضعیت queue |
| `health_storage` | GET | read | وضعیت storage |
| `health_time` | GET | read | همزمانی ساعت |
| `get_avatar_initials` | GET | read | آواتار از initials |
| `get_avatar_image` | GET | read | آواتار از URL |
---
## Query System
### Query Operators
Appwrite از سیستم Query مخصوص خود استفاده میکند:
```javascript
// Comparison
Query.equal("status", ["active"])
Query.notEqual("status", ["deleted"])
Query.lessThan("price", 100)
Query.lessThanOrEqual("price", 100)
Query.greaterThan("price", 50)
Query.greaterThanOrEqual("price", 50)
Query.between("price", 50, 100)
// String
Query.startsWith("name", "John")
Query.endsWith("email", "@example.com")
Query.search("title", "keyword") // Requires fulltext index
// Array
Query.contains("tags", ["featured"])
Query.isNull("deleted_at")
Query.isNotNull("published_at")
// Sorting & Pagination
Query.orderAsc("created_at")
Query.orderDesc("created_at")
Query.limit(25)
Query.offset(0)
Query.cursorAfter("document_id")
Query.cursorBefore("document_id")
// Selection
Query.select(["id", "name", "email"])
```
### Query در REST API
```bash
# Example: List active users, sorted by creation date
GET /databases/{dbId}/collections/{colId}/documents?queries[]=equal("status",["active"])&queries[]=orderDesc("$createdAt")&queries[]=limit(25)
```
---
## Tool Summary
| Handler | Tools | Description |
|---------|-------|-------------|
| Databases | 18 | Database, Collections, Attributes, Indexes |
| Documents | 12 | Document CRUD, Bulk ops, Transactions |
| Users | 12 | User management |
| Teams | 10 | Teams & Memberships |
| Storage | 14 | Buckets, Files, Image transformation |
| Functions | 14 | Functions, Deployments, Executions |
| Messaging | 12 | Email, SMS, Push notifications |
| System | 8 | Health checks, Avatars |
| **Total** | **100** | |
---
## Implementation Phases
### Phase I.1: Core (Database + System) - 38 tools
**هدف**: دسترسی اولیه به Appwrite Self-Hosted
1. **AppwritePlugin** class
2. **AppwriteClient** (REST client)
3. **Databases Handler** (18 tools)
4. **Documents Handler** (12 tools)
5. **System Handler** (8 tools)
### Phase I.2: Auth & Teams - 22 tools
**هدف**: مدیریت کاربران و تیمها
1. **Users Handler** (12 tools)
2. **Teams Handler** (10 tools)
**جمع**: 60 tools
### Phase I.3: Storage - 14 tools
**هدف**: مدیریت فایلها
1. **Storage Handler** (14 tools)
**جمع**: 74 tools
### Phase I.4: Functions & Messaging - 26 tools
**هدف**: قابلیتهای پیشرفته
1. **Functions Handler** (14 tools)
2. **Messaging Handler** (12 tools)
**جمع**: 100 tools
---
## Error Handling
### HTTP Status Codes
```python
async def handle_appwrite_error(response):
"""Handle Appwrite API errors"""
data = await response.json()
message = data.get("message", "Unknown error")
code = data.get("code", response.status)
error_type = data.get("type", "general_error")
if response.status == 400:
raise ValidationError(f"Bad Request: {message}")
elif response.status == 401:
raise AuthError("Invalid API key or missing authentication")
elif response.status == 403:
raise PermissionError(f"Permission denied: {message}")
elif response.status == 404:
raise NotFoundError(f"Resource not found: {message}")
elif response.status == 409:
raise ConflictError(f"Conflict: {message}")
elif response.status == 429:
raise RateLimitError("Rate limit exceeded. Try again later.")
elif response.status >= 500:
raise ServerError(f"Server error ({code}): {message}")
else:
raise AppwriteError(f"Error ({code}): {message}")
```
### Common Error Types
```
user_not_found - کاربر پیدا نشد
document_not_found - document پیدا نشد
collection_not_found - collection پیدا نشد
database_not_found - database پیدا نشد
storage_bucket_not_found - bucket پیدا نشد
storage_file_not_found - فایل پیدا نشد
document_already_exists - document تکراری
user_already_exists - کاربر تکراری
attribute_already_exists - attribute تکراری
```
---
## Security Considerations
### API Key Security
```
┌─────────────────────────────────────────────────────────────────┐
│ API Key Best Practices │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ✅ Best Practices: │
│ ├── Create separate keys for different purposes │
│ ├── Use minimal required scopes │
│ ├── Rotate keys periodically │
│ ├── Never expose keys in client-side code │
│ └── Use environment variables for storage │
│ │
│ ⚠️ Scope Recommendations: │
│ ├── Read operations: *.read scopes only │
│ ├── Write operations: specific *.write scopes │
│ └── Admin operations: all scopes + careful monitoring │
│ │
│ ❌ Never Do: │
│ ├── Log API keys (even partially) │
│ ├── Commit keys to version control │
│ ├── Share keys across different services │
│ └── Use single key for all operations │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### Permission System
```python
# Document-level permissions
permissions = [
"read(\"user:123\")", # Specific user can read
"write(\"user:123\")", # Specific user can write
"read(\"team:456\")", # Team members can read
"read(\"any\")", # Anyone can read (public)
"create(\"users\")", # Any authenticated user
"update(\"label:admin\")", # Users with admin label
]
```
---
## Example Usage
### Query Documents
```json
{
"tool": "list_documents",
"args": {
"site": "myappwrite",
"database_id": "main",
"collection_id": "posts",
"queries": [
"equal(\"status\", [\"published\"])",
"greaterThan(\"views\", 100)",
"orderDesc(\"$createdAt\")",
"limit(20)"
]
}
}
```
### Create User
```json
{
"tool": "create_user",
"args": {
"site": "myappwrite",
"user_id": "unique()",
"email": "user@example.com",
"password": "securePassword123",
"name": "John Doe"
}
}
```
### Upload File
```json
{
"tool": "create_file",
"args": {
"site": "myappwrite",
"bucket_id": "avatars",
"file_id": "unique()",
"file_content_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
"file_name": "avatar.png",
"permissions": ["read(\"any\")"]
}
}
```
### Execute Function
```json
{
"tool": "create_execution",
"args": {
"site": "myappwrite",
"function_id": "send-welcome-email",
"body": "{\"userId\": \"123\", \"template\": \"welcome\"}",
"async": false
}
}
```
### Send Email
```json
{
"tool": "send_message",
"args": {
"site": "myappwrite",
"message_id": "unique()",
"type": "email",
"targets": ["user-123"],
"subject": "Welcome to our platform!",
"content": "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
}
}
```
---
## Coolify Deployment Notes
### Finding Appwrite Credentials
در Coolify، بعد از deploy کردن Appwrite:
1. **URL**: از Coolify dashboard → Project → Appwrite → Domain
- معمولاً: `https://appwrite.yourdomain.com/v1`
2. **Project ID**:
- در Appwrite Console → Settings → Project ID
- یا از URL بعد از login
3. **API Key**:
- Appwrite Console → Project → Settings → API Keys → Create
- Scopes مورد نیاز را انتخاب کنید
### Docker Compose Services
```yaml
# Appwrite services on Coolify
services:
appwrite: # Main API - port 80
appwrite-realtime: # Realtime WebSocket
appwrite-executor: # Function execution
appwrite-worker-*: # Background workers
mariadb: # Database
redis: # Cache
influxdb: # Metrics (optional)
```
### Environment Variables (Appwrite Server)
```bash
# Key settings in Appwrite .env
_APP_ENV=production
_APP_DOMAIN=appwrite.yourdomain.com
_APP_DOMAIN_TARGET=appwrite.yourdomain.com
_APP_OPTIONS_ABUSE=enabled # Rate limiting
_APP_FUNCTIONS_RUNTIMES=node-18.0,python-3.9,php-8.0
```
---
## Endpoint Registration
### Endpoint Config
```python
# core/endpoints/config.py
EndpointType.APPWRITE: EndpointConfig(
path="/appwrite",
name="Appwrite Manager",
description="Appwrite Self-Hosted management (database, auth, storage, functions, messaging)",
endpoint_type=EndpointType.APPWRITE,
plugin_types=["appwrite"],
require_master_key=False,
allowed_scopes={"read", "write", "admin"},
tool_blacklist={
"manage_api_keys_create",
"manage_api_keys_delete",
"manage_api_keys_rotate",
"oauth_register_client",
"oauth_revoke_client",
},
max_tools=110,
),
```
---
## Comparison: Appwrite vs Supabase Tools
| Feature | Appwrite | Supabase |
|---------|----------|----------|
| Database Tools | 30 (Documents + Databases) | 18 (PostgREST) |
| Auth Tools | 22 (Users + Teams) | 14 (GoTrue) |
| Storage Tools | 14 | 12 |
| Functions Tools | 14 | 8 |
| Messaging Tools | 12 | 0 (not built-in) |
| System Tools | 8 | 6 |
| Admin Tools | - | 12 (postgres-meta) |
| **Total** | **100** | **70** |
**نکته**: Appwrite ابزارهای بیشتری دارد چون:
- Messaging built-in دارد
- Teams management جداگانه دارد
- Document/Collection model متفاوت است
- Image transformation پیشرفتهتر است
---
## Testing Checklist
### Unit Tests
- [ ] AppwriteClient authentication
- [ ] Database CRUD operations
- [ ] Document queries with all operators
- [ ] User management operations
- [ ] Team operations
- [ ] File upload/download
- [ ] Function execution
- [ ] Message sending
- [ ] Error handling
### Integration Tests
- [ ] Create database and collection
- [ ] CRUD documents with queries
- [ ] Create user and authenticate
- [ ] Upload and preview image
- [ ] Execute serverless function
- [ ] Send email through messaging
- [ ] Health check all services
- [ ] Rate limit handling
---
## Function Runtimes
### Supported Runtimes (v1.8+)
| Runtime | Versions |
|---------|----------|
| Node.js | 18.x, 20.x |
| Python | 3.9, 3.10, 3.11, 3.12 |
| PHP | 8.0, 8.1, 8.2, 8.3 |
| Ruby | 3.0, 3.1, 3.2, 3.3 |
| Java | 11, 17, 21 |
| Go | 1.18, 1.19, 1.20, 1.21 |
| Dart | 3.0, 3.1, 3.2, 3.3 |
| Rust | 1.60, 1.65, 1.70, 1.75 |
| C# | 8, 11, 12 |
| Swift | 5.5, 5.8, 5.9 |
| Kotlin | 1.8 |
---
## References
- [Appwrite Documentation](https://appwrite.io/docs)
- [Appwrite REST API Reference](https://appwrite.io/docs/apis/rest)
- [Appwrite Self-Hosting Guide](https://appwrite.io/docs/advanced/self-hosting)
- [Appwrite Server SDKs](https://appwrite.io/docs/sdks)
- [Appwrite GitHub Repository](https://github.com/appwrite/appwrite)
- [Appwrite Database Queries](https://appwrite.io/docs/products/databases/queries)
- [Appwrite Permissions](https://appwrite.io/docs/advanced/platform/permissions)
- [Appwrite Functions](https://appwrite.io/docs/products/functions)
- [Appwrite Messaging](https://appwrite.io/docs/products/messaging)
---
**Created**: 2025-12-02
**Author**: Claude AI Assistant
**Status**: Design Phase (Ready for Implementation)
