Skip to main content

Data Model

This page describes the entities a KNX Clarity organisation works with and how they relate. The goal is to make the platform's information architecture readable without disclosing implementation details — the underlying storage engine, table layout, and indexes are intentionally not part of this page.

Entities at a glance​

Organisation
├── Members (users with roles)
├── Customers
│   └── Owner profile (when the customer is also a portal user)
└── Projects
    ├── Project members (users assigned to the project)
    ├── Project shares (customers granted read-access)
    │   └── Redaction rules (rooms hidden from the customer)
    ├── ETS files (versioned uploads)
    ├── Floor plans
    ├── Rooms
    │   └── Devices
    │       ├── Group addresses (linked via device functions)
    │       └── Device functions
    ├── Service cases
    │   └── Comments + attachments
    ├── Change requests
    ├── Activity feed
    ├── Audit log entries
    ├── Milestones (basic programming, handover, escrow, …)
    ├── Escrow record
    └── Transfer request (when ownership moves between orgs)

Core entities​

Organisation​

The top-level container. Billing, member management, the audit log, and every project all sit underneath an organisation. A user belongs to zero or more organisations; cross-organisation access is never implicit.

Member​

A user attached to an organisation, with a memberRole that determines what they can do. The current roles are admin, integrator, and field_staff (see Team for the role matrix).

Customer​

The building owner / end-customer record an integrator captures in their CRM-style "Customers" list. A customer may or may not have a sign-in account; once they accept an invitation, the customer record is linked to their portal account so they can view shared projects.

Owner profile​

The portal-side identity of a customer once they've signed in. A single owner profile can be linked to customer records from multiple integrators — useful if a building owner works with more than one integrator.

Project​

A building automation project. Belongs to one organisation and optionally references one customer. Holds the building name, address, status (active, completed, archived, escrow), and the milestones that track the project's lifecycle.

Project share​

Grants a specific customer read-access to a specific project. The share carries optional redaction rules — currently a list of room IDs the integrator wants to hide from the customer; hiding a room transitively hides its devices, group addresses, and service cases.

ETS file​

A versioned upload of an .knxproj export. Each upload is a new version, never an overwrite. Parsing extracts the rooms, devices, group addresses, and device functions captured below.

Floor plan​

A PDF or image plan attached to a project. Plans can be annotated with per-room markers; markers are visible to the customer when the floor plan is flagged as customer-visible.

Room → Device → Group address / Function​

The parsed KNX structure. Rooms belong to a project; devices belong to a room; device functions and group addresses hang off devices. Group addresses also carry the canonical KNX address notation (1/2/3) and the datapoint type.

Service case​

A ticket scoped to a project. Has a status (open, in_progress, resolved, closed), a priority, an optional room/device anchor, and a thread of comments with attachments.

Change request​

A customer-initiated request for a change in their shared project. The integrator approves, rejects, or asks for more details; the customer sees a status thread.

Milestone​

A named checkpoint in the project lifecycle: basic programming confirmed, partial invoice sent/paid, ETS file released, handover confirmed. Confirming a milestone is gated by role — some are integrator-only, some are customer-confirmable.

Escrow record / Transfer request​

Optional. An escrow record is the integrator's deliverable package held back from the customer until a handover step is confirmed. A transfer request is the cross-organisation handover when ownership moves from one integrator to another (e.g. when the building owner switches service providers).

Activity feed & Audit log​

Every meaningful change writes one or both of:

  • An activity entry — surfaced in the project's "Activity" tab and the global notifications feed, designed for awareness.
  • An audit log entry — surfaced under Settings → Audit log, designed for compliance review. Admin-only.

Relationships in plain English​

  • One organisation has many projects; each project belongs to exactly one organisation.
  • A project may be assigned to at most one customer; a customer may be assigned to many projects.
  • A project may be shared with many customer users; a customer user may have shares across many projects (typical for owner-profile identities that span several integrators).
  • An ETS file belongs to one project; uploading a new version doesn't replace the old one, it stacks on top.
  • A service case belongs to one project; comments and attachments belong to one service case.

Questions​

Use the in-app feedback button (bottom-right on every page) or email info@knx-clarity.com.