document ACL and other tables

documentation/database.md

@@ -118,6 +118,48 @@ Tables whose rows represent documents
 | trunk_id | If set, the current document is a fork (as of 2024-04-15, only from a tutorial), and this column references the original document |
 | type | If set, the current document is a special one (as specified in [DocumentType](https://github.com/gristlabs/grist-core/blob/4567fad94787c20f65db68e744c47d5f44b932e4/app/common/UserAPI.ts#L123)) |
 
+### `aliases` table
+
+Aliases for documents.
+
+FIXME: What's the difference between `docs.url_id` and `alias.url_id`?
+
+| Column name | Description |
+| ------------- | -------------- |
+| url_id | The URL alias for the doc_id |
+| org_id | The organisation to which the document belong to |
+| doc_id | The document id |
+
+### `acl_rules` table
+
+Permissions for to access either a document, workspace or an organisation.
+
+| Column name | Description |
+| ------------- | -------------- |
+| id | The primary key |
+| permissions | The permissions granted to the group. see below. |
+| type | Either equals to `ACLRuleOrg`, `ACLRuleWs` or `ACLRuleDoc` |
+| org_id | The org id associated to this ACL (if set, workspace_id and doc_id are null) |
+| workspace_id | The workspace id associated to this ACL (if set, doc_id and org_id are null) |
+| doc_id | The document id associated to this ACL (if set, workspace_id and org_id are null) |
+| group_id | The group of users for which the ACL applies |
+
+The permissions are stored as an integer which is read in its binary form which allows to make bitwise operations:
+
+| VIEW | UPDATE | ADD | REMOVE | SCHEMA_EDIT | ACL_EDIT | (reserved) | PUBLIC |
+| --------------- | --------------- | --------------- | --------------- | --------------- | ---------- | --------- | ---- |
+| can view | can update | can add | can remove | can change schema of tables | can edit the ACL (docs) or manage the teams (orgs and workspaces) of the resource | (reserved bit for the future) | virtual bit meaning that the resource is shared publicly |
+| +0b00000001 | +0b00000010 | +0b00000100 | +0b00001000 | +0b00010000 | +0b00100000 | +0b01000000 | +0b10000000 |
+
+You notice that the permissions can be then composed:
+ - EDITOR permissions = `VIEW | UPDATE | ADD | REMOVE` = `0b00000001+0b00000010+0b00000100+0b00001000` = `0b00001111` = `15`
+ - ADMIN permissions = `EDITOR | SCHEMA_EDIT` = `0b00001111+0b00010000` = `0b00011111` = `31`
+ - ...
+
+For more details about that part, please refer [to the code](https://github.com/gristlabs/grist-core/blob/192e2f36ba77ec67069c58035d35205978b9215e/app/gen-server/lib/Permissions.ts).
+
+
+### `prefs` table
 
 ### The migrations