people/docs/models.md

What is People?

Space Odyssey is a dynamic organization. They use the People application to enhance teamwork and streamline communication among their co-workers. Let's explore how this application helps them interact efficiently.

Let's see how we could interact with Django's shell to recreate David's environment in the app.

Profile contact

The system identifies Dave through the sub associated with his OIDC session. The OIDC should also provide his email address.

Note: as some Identity Providers do not provide a constant sub, the system should be able to fallback to the email address to find it the user is already in the database.

When Dave logs in for the first time, the system checks if he is already in the database. If not a new user is created for him.

Users needs to be linked to an Organization (see organizations.md).

space_odyssey, _created = Organization.objects.get_or_create(...)

david_user = User.objects.create(
    organization=space_odyssey,
    language="en-us",
    timezone="America/Los_Angeles",
    name="David Bowman",
    sub="1234567890",
    email="david.bowman@spaceodyssey.com",
)

The system then creates a profile contact for Dave, based on the information provided by the OIDC:

david_profile_contact = Contact.objects.create(
    owner=david_user,
    user=david_user,  # this means it's the user's profile contact
    full_name="David Bowman",
    data={
        "emails": [
            {"type": "Work", "value": "david.bowman@spaceodyssey.com"},
        ],
    },
)

Future feature: Dave will be prompted to confirm the details of the base contact stored in the database and fill the details for a better profile.

His profile contact will be updated with the new information.

Contact.objects.filter(user=david_user, owner=david_user).update(
    short_name="Dave",
    data={
        "emails": [
            {"type": "Work", "value": "david.bowman@spaceodyssey.com"},
        ],
        "phones": [
            {"type": "Work", "value": "(123) 456-7890"},
        ],
        "addresses": [
            {
                "type": "Work",
                "street": "123 Main St",
                "city": "Cityville",
                "state": "CA",
                "zip": "12345",
                "country": "USA",
            }
        ],
        "links": [
            {"type": "Website", "value": "http://www.spaceodyssey.com"},
            {"type": "Twitter", "value": "https://www.twitter.com/dbowman"},
        ],
        "organizations": [
            {
                "name": "Space Odyssey Corporation",
                "department": "IT",
                "jobTitle": "AI Engineer",
            },
        ],
    }
)

David's profile contact is available to all users of his company/organization.

Contact override

During a Space conference he attended, Dave met Dr Ryan Stone, a medical engineer who gave him her personal email address (because she will quit the company she works for). Ryan is already present in the system.

Dave can add it to his private version of the contact:

ryan_user = User.objects.create(
    organization=space_odyssey,
    language="en-us",
    timezone="America/Los_Angeles",
    name="Ryan Stone",
    sub="0987654321",
    email="ryan.stone@spaceodyssey.com",
)

ryan_profile_contact = Contact.objects.create(
    user=ryan_user,
    owner=ryan_user,
    full_name="Ryan Stone",
    short_name="Dr Ryan",
    data={
        "emails": [
            {"type": "Work", "value": "ryan.stone@hubblestation.com"},
        ],
    },
)

david_ryan_contact = Contact.objects.create(
    override=ryan_profile_contact,
    owner=david_user,
    full_name="Ryan Stone",
    short_name="Dr Ryan",
    data={
        "emails": [
            {"type": "Home", "value": "ryan@stone.com"},
        ],
    },
)

Personal contacts

Dave met a lot of people during the last Opensource Experience event. He can add them to his personal contacts:

julie_personal_contact = Contact.objects.create(
    owner=david_user,
    full_name="Julie Powell",
    short_name="Julie",
    data={
        "emails": [
            {"type": "Work", "value": "julie.powell@example.com"},
        ],
        "phones": [
            {"type": "Work", "value": "(123) 456-7890"},
        ],
    },
)

These contacts are only available to Dave.

Contacts from shared directories

This is a future feature that will allow Dave to access contacts from shared directories. Shared directories will provide contacts for all users from several organizations.

Team Collaboration

Dave wants to form a team with Ryan and other colleagues to work together better on using the organization's digital tools for their projects.

Dave would like to create a team with Ryan and some other colleagues, to enhance collaboration throughout their projects:

projectx = Team.objects.create(name="Project X")

A team can for example be used to create an email alias or to define role based access rights (RBAC) in a specific application or all applications of the organization's digital Suite.

Having created he team, Dave is automatically assigned the "owner" role. He invites Ryan, granting an "administrator" role to her so she can invite her own colleagues. Both of them can then proceed to invite other colleagues as simple members. If Ryan wants, she can upgrade a colleague to "administrator" but only David can upgrade someone to the "owner" status:

TeamAccess.objects.create(user=david_user, team=projectx, role="owner")
TeamAccess.objects.create(user=ryan_user, team=projectx, role="administrator")
TeamAccess.objects.create(user=julie_user, team=projectx, role="member")

Role	Member	Administrator	Owner
Can view team	✔	✔	✔
Can set roles except for owners		✔	✔
Can set roles for owners			✔
Can delete team			✔

Importantly, the system ensures that there is always at least one owner left to maintain control of the team.

Models overview

The following graph represents the application's models and their relationships:

erDiagram
  %% Models

  Contact {
    UUID id PK
    Contact base
    User owner
    string full_name
    string short_name
    json data
    DateTime created_at
    DateTime updated_at
  }

  User {
    UUID id PK
    Contact profile_contact
    string language
    string timezone
    boolean is_device
    boolean is_staff
    boolean is_active
    DateTime created_at
    DateTime updated_at
  }

  Identity {
    UUID id PK
    User user
    string sub
    Email email
    boolean is_main
    DateTime created_at
    DateTime updated_at
  }

  Team {
    UUID id PK
    string name
    DateTime created_at
    DateTime updated_at
  }

  TeamAccess {
    UUID id PK
    Team team
    User user
    string role
    DateTime created_at
    DateTime updated_at
  }

  %% Relations
  User ||--o{ Contact : "owns"
  Contact ||--o{ User : "profile for"
  User ||--o{ TeamAccess : ""
  Team ||--o{ TeamAccess : ""
  Identity ||--o{ User : "connects"
  Contact }o--|| Contact : "overrides"