Data Associations

A Data Association (DomainAssociation) defines how database entities relate to one another (e.g., a User has many Posts, or an Order has many LineItems).

The Serverless Engine automatically translates these associations into standard foreign keys, index structures, and database constraints.

---

Designing Associations: Parent-to-Child Priority

When designing your database schema in the Domain Modeler, always prioritize defining associations from the Parent entity to the Child entity (e.g., defining User → Posts or User → Profile).

Why Parent-to-Child Matters for API Routing

While relational databases support bidirectional queries, the API Modeler relies on Parent-to-Child associations to generate nested endpoints.

• Hierarchical Routes: If you want to structure your endpoints hierarchically (e.g., /users/{userId}/posts to list posts belonging to a specific user), the Serverless Engine requires an association pointing from the parent (User) to the child (Post).
• Runtime Recognition: If you only define the inverse “belongs to” association (e.g., Post pointing back to User), the runtime will not recognize the nested relationship, and you will not be able to configure nested child routes in the API Modeler.
• Coexistence: You can define both directions if needed, but the parent-to-child direction is a strict prerequisite for nested API endpoint structure.

---

Association Parameters

When you configure an association in the Domain Modeler, you define the following options:

1. Targets

The association specifies one or more target entities it connects to. For example, a User entity has an association pointing to the target Post entity.

2. Cardinality (Multiple) & Many-to-Many (M:N) Relationships

The Multiple toggle checkbox determines the cardinality of the relationship:

• multiple: false (One-to-One / Many-to-One): The current entity holds a reference to a single target record (e.g., User has a Profile with multiple: false, mapping to a single foreign key reference).
• multiple: true without an M:N Semantic (One-to-Many / 1:N): The relationship represents a list of target records using a standard Foreign Key constraint on the target table, avoiding unnecessary pivot tables.
• multiple: true with an M:N Semantic (Many-to-Many / M:N): When multiple: true is combined with a dedicated M:N Semantic module (such as OrganizationMembers), the platform provisions a physical M:N pivot table in the underlying database.

---

Many-to-Many (M:N) Relationships

To eliminate raw join table complexity and ensure every relationship conveys clear business meaning, the platform handles M:N relationships through Semantic Modules.

1. Semantic-Driven Relationships

Instead of creating generic join tables, you tag relationships with specific M:N semantic modules (such as OrganizationMembers or Tags). This imparts clear business logic that both humans and AI agents can understand.

2. Relationship Edge Properties

When you apply an M:N semantic module (such as OrganizationMembers), the system automatically provisions standard Relationship Edge Properties (such as member role or status). In the UI, you toggle which edge properties to enable for your API and can customize options like display names or allowed enum values, while the platform maintains core data types and database structure.

3. Dual-Sided Modeling & Automatic Single Link Table

If you want to access a Many-to-Many relationship from both entities in your API:

1. Draw the association from Entity A to Entity B and tag it with an M:N semantic (e.g., OrganizationMembers).
2. Draw the reciprocal association from Entity B to Entity A and tag it with the exact same semantic module (OrganizationMembers).

The platform automatically manages a single underlying link table in the database while allowing you to configure API endpoints on either or both entities in the API Modeler (such as /organizations/{orgId}/users and /users/{userId}/organizations).

---

Association Semantics

You can attach specialized access control, tenancy, and M:N tags directly to associations to configure automated runtime logic:

• OrganizationMembers: M:N semantic linking an Organization to User members with pivot edge attributes.
• ResourceOwnerIdentifier: Binds a resource directly to the logged-in system user. Tells the security engine who owns the record, enabling automatic filters and row-level access control.
• RelationalResourceOwner: Binds a sub-resource to a parent resource (e.g., a Comment pointing to its parent Post), inheriting the owner permissions transitively.

---

Relational Constraints & Database Mapping

• Foreign Keys: Associations with multiple: false are generated in the PostgreSQL schema as standard foreign key columns.
• Cascading Deletes: When deleting records, parent-child relationships automatically support cascading deletions if specified, preventing orphan rows.
• Automatic Indexing: The deployment engine automatically creates database indexes on foreign key relationship columns to ensure sub-150ms query execution times.