Entity Model & Key Relationships

ZeyOS organizes data around a set of core entities that are linked together across modules. Understanding how these entities relate to each other will help you navigate the platform and keep your data consistent.

Core Entities at a Glance

Entity	What it represents	Module
Contact	A person or company in the address book	Contacts
Account	A business relationship (customer, supplier, etc.)	Business Accounts
Address	A location tied to an account-contact pair	Business Accounts > Addresses
User	A system login with credentials and permissions	User Management
Transaction	A sales or purchase document (quote, order, invoice, etc.)	Invoicing / Procurement
Item	A product or service in the inventory	Inventory
Message	An email or internal communication	Messages
Task	A to-do or work item	Projects & Tasks
Ticket	A support or service request	Tickets
Note	A knowledge-base or documentation entry	Notes
Contract	A recurring billing or service agreement	Contracts
Opportunity	A sales lead in the pipeline	Opportunities
Campaign	A marketing initiative	Campaigns
Payment	A cash ledger entry (receipt or disbursement)	Payments

Contact, Account, and Address

These three entities form the foundation of business data in ZeyOS:

Text

Contact (Person or Company)
    ↕ linked via account.contact
Account (Customer, Supplier, Prospect, Competitor, Employee)
    ↕ address requires both
Address (Billing, Shipping, Procurement, Collection)

• A Contact is a person or company record — it stores who someone is (name, phone, email, photo).
• An Account is a business relationship — it stores what role an entity plays in your business (customer, supplier, etc.) and links to a primary contact.
• An Address always belongs to both an account and a contact. This means you can have different addresses for the same account depending on which contact person is involved, and you can type addresses by purpose (billing, shipping, procurement, collection).

One contact can have multiple accounts (e.g., a company that is both your customer and your supplier). One account can have multiple contacts (e.g., different people at the same customer organization). Addresses sit at the intersection.

User vs Contact vs Account

These three concepts are often confused. Here is how they differ:

Concept	Purpose	Managed in
User	A system login — grants access to ZeyOS with a username, password, and permissions	Administration > User Management
Contact	A person or company record in the address book — stores name, phone, email	Contacts
Account	A business relationship record — stores account type, customer/supplier number, tax ID	Business Accounts

Key points:

• A User can be linked to a Contact (via users.contact → contacts.ID). This synchronizes the user's profile with the contact's data. It is recommended to always link users to contacts.
• An Account links to a Contact (via accounts.contact → contacts.ID). The contact provides the name, phone, and email displayed on the account.
• An employee Account (type = Employee) is not the same as a User. A person can exist as an employee account without having a ZeyOS login, and a user can exist without being listed as an employee account.

Ownership and Assignment

Most entities in ZeyOS share two common fields:

Field	Purpose
Owner (ownergroup)	Controls visibility — determines which group can see the record. Set to null for public (everyone can see it), or to a specific group ID.
Assigned User (assigneduser)	The user responsible for managing this record. Used for workload distribution and filtering ("Show my items only").

These fields appear on contacts, accounts, transactions, tasks, tickets, notes, messages, and most other entities. For a deeper explanation, see Groups & Permissions and Status & Visibility.

Transactions and the Billing Chain

Transactions (quotes, orders, deliveries, invoices, credit notes) are the backbone of financial data:

Text

Transaction
  → account   (which customer or supplier)
  → item      (which product, if single-item transaction)
  → contract  (which contract, if recurring)
  → assigneduser (who is responsible)

Transactions flow through stages — a quote becomes an order, which becomes a delivery, which becomes an invoice. Each conversion creates a new, linked transaction. For details, see Billing & Finance.

Associations and Events

Any entity can be linked to any other entity through two mechanisms:

• Associations — Explicit links between records (e.g., linking a message to a contact, or a task to a transaction). Created via the + button in the right sidebar.
• Events — Calendar entries or reminders attached to a record (e.g., a follow-up call scheduled on a contact, or a deadline reminder on a task).

These cross-module links are what makes ZeyOS an integrated platform rather than a collection of separate tools. For details, see Events & Associations.

Common Fields Across Modules

Most ZeyOS entities share these standard fields:

Field	Description
ID	Unique identifier (auto-generated)
Creator	The user who created the record
Created	Timestamp of creation
Last Modified	Timestamp of last change
Owner	Visibility group (see above)
Assigned User	Responsible user (see above)
Status	Current workflow status (varies by module)
Visibility	Regular, Archived, or Deleted
Tags	User-defined labels for categorization
Fork	Module fork ID (for custom module variants)

Related Topics

• UI Basics — General interface patterns
• Groups & Permissions — How ownership and group visibility work
• Status & Visibility — Status workflows and record visibility
• Tags & Categories — Organizing records with tags
• Events & Associations — Cross-module linking