---
title: "Surface concepts"
url: https://developers.dagio.ai/concepts/
---

# Surface concepts

   
                         
                                                                                    
                
              
         
   

## Organize without mixing responsibilities

Surface separates an activity’s context, organization and contents. This lets you reuse an app, share a particular record and connect Workspaces without moving their data.

| Concept   | Expected content                                        | Clients/Quotes example                   |
| --------- | ------------------------------------------------------- | ---------------------------------------- |
| Portfolio | Workspaces and shared context                           | The Boreal business                      |
| Workspace | An app or work domain defined by a Model                | Clients or Quotes                        |
| Space     | Content organized by responsibility                     | Client directory, procedures, follow-ups |
| Surface   | An identified, editable and connected record or content | North Studio record                      |
| Object | Stable, addressable element within a Surface | Constraints Rich text object |
| Model     | Reusable structure and behavior definition              | Clients app published in the catalog     |

## Choose a Space role

**Knowledge** holds references used to understand and carry out work. **Data** holds structured business objects. **Work** holds ongoing work, dependencies and decisions. **Product** organizes results and deliverables intended for use.

A final quote belongs to the business result; preparing it has its own work steps. A sales procedure is knowledge, and does not become a task because AI reads it.

## Definition and instance

A Model defines a Client’s Fields, Actions and views. A Clients Workspace applies that definition. North Studio is an instance with its own values and links. Editing an instance does not change the Model; changing the Model goes through composition, validation and publication.

## Interfaces preserve ownership

A table, graph and links panel can display the same record. They read the same identities and invoke the same authorized operations. The table does not own a separate copy of the client; a link selects an existing record rather than copying its contact details.

## Navigate between applications and personal Spaces

The Surface menu opens Dashboard, Portfolio, Data, Knowledges, Contents and Workers. Portfolio
contains your applications. The other collections let you create personal Spaces without creating
an application. Search filters each collection automatically during typing, with a loading
indicator. Data views use the available width without a left sidebar. Pin an application in Portfolio to keep it available under Applications in the Surface menu, with its configured icon. Marketplace is available from Portfolio.

Inside an application, the sidebar lists its Spaces. Knowledge and Content show their Surface
hierarchy, with categories or folders and root Surfaces. Use the breadcrumb to return to the
collection or application, or switch to another Space in the same application. Pending editor
changes are prepared before navigation; a failed save keeps you in the current context.
In Knowledge and Content, the general menu belongs to Overview. The divider can collapse the
sidebar by its central control, double-click or dragging to the left edge. The collapsed rail
remains clickable and shows hover feedback; its resize handle is hidden.



## Account menu

Open your avatar menu for My profile, Trash, Archives and Sign out. Explore provides Marketplace,
Invitations for the active Workspace, Help, Developers and a Light/Dark theme submenu. Subscribe
opens the account portal for Free accounts. Trash, Archives and Help currently provide their window
only; their content management will be added separately. Developer documentation is available at
https://developers.dagio.ai/.

<!-- surface-examples:start -->

## Applied examples : From Workspace to record

The Clients destination opens the data; the profile defines its editable record.

### Configuration

Fragment placed in `composition.navigation[]`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-model-foundation/).

```json
{
  "key": "clients",
  "label": "Clients",
  "icon": "users",
  "kind": "collection",
  "spaceKey": "clients",
  "definitionPaths": [
    "workspace/clients/surface/client"
  ],
  "queryKey": "clients",
  "formKey": null
}
```

### Variation and connection

Fragment placed in `presentation.recordProfiles[]`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-record-profile/).

```json
{
  "key": "client",
  "definitionPaths": [
    "workspace/clients/surface/client"
  ],
  "editActionKey": "edit-client",
  "identity": {
    "title": {
      "kind": "field",
      "fieldPath": "fields/company"
    },
    "avatar": {
      "kind": "initials",
      "maximumLetters": 2
    },
    "subtitle": {
      "kind": "field",
      "fieldPath": "fields/status"
    }
  },
  "valueLabels": [
    {
      "fieldPath": "fields/status",
      "values": [
        {
          "value": "prospect",
          "label": "Prospect"
        },
        {
          "value": "active",
          "label": "Active"
        }
      ]
    }
  ],
  "card": {
    "summary": {
      "kind": "field",
      "fieldPath": "fields/notes"
    },
    "tags": {
      "namespace": "user",
      "maximumVisible": 3
    },
    "metricKeys": [],
    "openLabel": "Open client"
  },
  "queryBindings": [],
  "metrics": [],
  "detail": {
    "primaryActionKey": null,
    "creationActionKeys": [],
    "actionKeys": [],
    "sections": [
      {
        "kind": "fields",
        "key": "follow-up",
        "label": "Client follow-up",
        "fieldPaths": [
          "fields/notes",
          "fields/status"
        ]
      }
    ],
    "settings": {
      "fieldPaths": [
        "fields/email"
      ]
    },
    "tags": {
      "namespace": "user",
      "maximumVisible": 3
    },
    "relatedGroups": [],
    "primaryActionLabel": null
  }
}
```

### UI layout example

The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations.

1. Clients · Data
2. References · Knowledge
3. Preparation · Work
4. Quotes · Product

<!-- surface-examples:end -->