WIP

Author: ymc9

versioned_docs/version-3.x/_components/ZModelVsPSL.tsx

@@ -7,7 +7,7 @@ interface ZModelVsPSLProps {
 
 const ZModelVsPSL: FC<ZModelVsPSLProps> = ({ children }) => {
     return (
-        <Admonition type="info" title="🔋 ZModel vs PSL">
+        <Admonition type="info" title="🔋 ZModel vs Prisma Schema">
             {children}
         </Admonition>
     );

versioned_docs/version-3.x/migration/_category_.yml

@@ -2,6 +2,3 @@ position: 4
 label: Migration
 collapsible: true
 collapsed: true
-link:
-    type: generated-index
-    title: Migration

versioned_docs/version-3.x/migration/overview.md renamed to versioned_docs/version-3.x/migration/index.md

@@ -2,6 +2,3 @@ position: 2
 label: Data Modeling
 collapsible: true
 collapsed: true
-link:
-    type: generated-index
-    title: Data Modeling

versioned_docs/version-3.x/modeling/_category_.yml

@@ -3,7 +3,40 @@ sidebar_position: 11
 description: Breaking down complex schemas into multiple files
 ---
 
+import ZModelVsPSL from '../_components/ZModelVsPSL';
+
 # Multi-file Schema
 
+<ZModelVsPSL>
+Prisma uses an implicit approach that simply merges all schema files in a folder. ZModel uses explicit `import` syntax for better clarity and flexibility.
+</ZModelVsPSL>
+
+When your schema grows large, you can break them down to smaller files and stitch them together using the `import` statement.
+
+```zmodel title="zenstack/user.zmodel"
+import './post'
+
+model User {
+    id    Int   @id
+    posts Post[]
+}
+```
+
+```zmodel title="zenstack/post.zmodel"
+import './user'
+
+model Post {
+    id       Int    @id
+    content  String
+    author   User   @relation(fields: [authorId], references: [id])
+    authorId Int
+}
+```
+
+```zmodel title="zenstack/schema.zmodel"
+import './user'
+import './post'
+```
 
+After type-checking, these files are merged into a single schema AST before passed to the downstream tools.
 

versioned_docs/version-3.x/modeling/overview.md renamed to versioned_docs/version-3.x/modeling/index.md

@@ -3,5 +3,36 @@ sidebar_position: 11
 description: ZenStack plugins
 ---
 
+import ZModelVsPSL from '../_components/ZModelVsPSL';
+
 # Plugin
 
+<ZModelVsPSL>
+ZenStack's "plugin" concept replaces PSL's "generator".
+</ZModelVsPSL>
+
+Plugin is a powerful mechanism that allows you to extend ZenStack at the schema, CLI, and runtime levels. This section only focuses on how to add plugins to your ZModel. Please refer to the [Plugin Development](../reference/plugin-dev.md) section for more details on how to develop plugins.
+
+## Adding plugins to ZModel
+
+Let's take a look at the following example:
+
+```zmodel
+plugin myPlugin {
+    provider = 'my-zenstack-plugin'
+    output = './generated'
+}
+```
+
+A plugin declaration involves three parts:
+
+1. A unique name
+2. A `provider` field that specifies where to load the plugin from. It can be a built-in plugin (like `@core/prisma` here), a local folder, or an npm package.
+3. Plugin-specific configuration options, such as `output` in this case.
+
+A plugin can have the following effects to ZModel:
+
+- It can contribute custom attributes that you can use to annotate models and fields.
+- It can contribute code generation logic that's executed when you run the `zenstack generate` command.
+
+Plugins can also contribute to the ORM runtime behavior, and we'll leave it to the [ORM](../orm/plugins/) part to explain it in detail.

versioned_docs/version-3.x/modeling/multi-file.md

@@ -17,7 +17,7 @@ When modeling non-trivial applications, the need of an "Object-Oriented" kind of
 - Something **IS-A** more abstract type of thing.
 - Something **HAS-A/HAS-many** a more abstract type of thing(s).
 
-Imagine we're modeling a content library system where users own different types of content: posts, videos, images, etc. They share some common traits like name, creation date, owner, etc., but have different specific fields.
+Imagine we're modeling a content library system where users own different types of content: posts, images, videos, etc. They share some common traits like name, creation date, owner, etc., but have different specific fields.
 
 It may be tempting to use mixins to share the common fields, however it's not an ideal solution because:
 
@@ -32,3 +32,91 @@ There are [two main ways](https://www.prisma.io/docs/orm/prisma-schema/data-mode
 :::
 
 ## Modeling polymorphism
+
+Modeling polymorphism in ZModel is similar to designing an OOP class hierarchy - you introduce a base model and then extend it with concrete ones.
+
+Here's how it looks for our content library example:
+
+```zmodel
+model User {
+    id       Int       @id
+    contents Content[]
+}
+
+model Content {
+    id        Int      @id
+    name      String
+    createdAt DateTime @default(now())
+    owner     User     @relation(fields: [ownerId], references: [id])
+    ownerId   Int
+    // highlight-next-line
+    type      String
+
+    // highlight-next-line
+    @@delegate(type)
+}
+
+model Post extends Content {
+    content String
+}
+
+model Image extends Content {
+    data Bytes
+}
+
+model Video extends Content {
+    url String
+}
+```
+
+```mermaid
+erDiagram
+	User {
+        id Int PK
+	}
+    Content {
+        id Int PK
+		name String
+        createdAt Date
+        ownerId Int FK
+        type String
+    }
+    User ||--o{ Content: owns
+    Post {
+        id Int PK
+        content String
+    }
+    Post ||--|| Content: delegates
+    Image {
+        id Int PK
+        data Bytes
+    }
+    Image ||--|| Content: delegates
+    Video {
+        id Int PK
+        url String
+    }
+    Video ||--|| Content: delegates
+```
+
+There are two special things about polymorphic base model:
+
+1. It must have a "discriminator" field that stores the concrete model type that it should "delegate" to. In the example above, the `type` field serves this purpose. It can be named anything you like, but must be of `String` or enum type.
+2. It must have a `@@delegate` attribute. The attribute serves two purposes: it indicates that the model is a base model, and it designates the discriminator field with its parameter.
+
+You can also have a deep hierarchy involving multiple level of base models. Just need to make sure each base model has its own discriminator field and `@@delegate` attribute. Extending from multiple base models directly is not supported.
+
+## Migration behavior
+
+The migration engine takes care of mapping both the base model and the concrete ones to tables, and creates one-to-one relations between the base and each of its derivations.
+
+To simplify query and conserve space, the base and the concrete are assumed to share the same id values (this is guaranteed by the ORM when creating the records), and consequently, the concrete model's id field is also reused as the foreign key to the base model. So, for a `Post` record with id `1`, the base `Content` record also has id `1`.
+
+## ORM behavior
+
+The ORM hides the delegate complexities and provides a simple polymorphic view to the developers:
+
+1. Creating a concrete model record automatically creates the base model record with the same id and proper discriminator field.
+2. Querying with the base model will return entities with concrete model fields.
+
+We'll revisit the topic in details in the [ORM](../orm/) part.

versioned_docs/version-3.x/modeling/plugin.md

@@ -2,6 +2,3 @@ position: 3
 label: ORM
 collapsible: true
 collapsed: true
-link:
-    type: generated-index
-    title: ORM