Accounts — models¶

Responsibilities¶

The accounts app models identity, authentication-adjacent data, workforce profile data, device/session tracking, onboarding through invites, and engineer capability data.

In this project, accounts is responsible for:

the custom User model
workforce profile and preferences
work schedules and weekly hour derivation
mobile/web device registration and refresh-token session tracking
invitation-based onboarding for internal and customer users
skills and user-to-skill assignments

It is not responsible for organization structure itself, but it links closely to orgs, teams, and other domain apps.

Main models¶

User¶

Custom application user model extending Django AbstractUser.

Fields
Standard Django auth fields from AbstractUser
ms_oid: external Microsoft/Azure object identifier
skills: many-to-many relation to Skill through UserSkill
Constraints
No extra custom DB constraints beyond inherited auth model behavior
Relationships
One-to-one with UserProfile
One-to-one with UserSettings
One-to-one with UserWorkSchedule
One-to-many with Device
One-to-many with invites created via created_invites
One-to-many with invites accepted via accepted_invites
One-to-many with invites cancelled via cancelled_invites
Many-to-many with Skill through UserSkill

The custom user model is the identity anchor for the rest of the app.

UserProfile¶

Operational workforce profile for a user.

Fields
Basic identity and display:
- display_name
- phone
- job_title
- avatar
- preferred_name
- pronouns
Localization:
- timezone
- locale
- week_start
General profile:
- bio
- department
- location
- employee_id
- start_date
Employment/workforce:
- employment_type
- employment_status
- manager
Dispatch/planning context:
- home_base
- primary_region
- travel_radius_km
- has_company_vehicle
- driver_license_type
- can_travel_internationally
- availability_status
- is_dispatchable
- on_call
- assignment_notes
Emergency contact:
- emergency_contact_name
- emergency_contact_phone
- emergency_contact_relation
Workload:
- minimum_weekly_hours
Constraints
week_start validated to be between 0 and 6
travel_radius_km and minimum_weekly_hours must be non-negative when set
Relationships
One-to-one with User
Optional self-referential workforce manager via manager -> User

This model is intentionally broader than a simple user profile. It is the workforce identity record used by planning and operations.

Derived behavior¶

effective_minimum_weekly_hours
Uses minimum_weekly_hours when set
Falls back to UserWorkSchedule.derived_weekly_hours
Falls back to 40.00 hours if neither is available

UserWorkSchedule¶

A per-user default work schedule.

Fields
default_break_minutes
updated_at
Constraints
One schedule per user
Relationships
One-to-one with User
One-to-many with UserWorkDay

This model stores the weekly schedule container rather than daily rows directly.

Derived behavior¶

derived_weekly_hours
Sums enabled workdays with valid time ranges
Subtracts day-specific break or default break
Returns None if no usable enabled workdays exist

UserWorkDay¶

A single weekday row within a user work schedule.

Fields
weekday
enabled
start_time
end_time
break_minutes
Constraints
Unique per (schedule, weekday)
Ordered by weekday
Relationships
Foreign key to UserWorkSchedule

This model gives the frontend a stable 7-day schedule payload and supports schedule-derived hour calculations.

UserSettings¶

Frontend-facing UI and preference settings for a user.

Fields
language
theme
gradient
card_style
card_color
font_family
font_scale
accent
density
reduce_motion
preferences JSON field
Constraints
One settings row per user
Relationships
One-to-one with User

This model is used for user-level frontend customization and feature preferences, especially notification preferences.

Skill¶

Canonical skill/certification directory entry.

Fields
name
category
is_active
Constraints
name is unique
Relationships
Many-to-many with User through UserSkill

This model is intentionally small and stable so it can serve as a reusable directory across planning and staffing flows.

UserSkill¶

Assignment of a skill to a specific user.

Fields
user
skill
level
valid_from
valid_until
notes
Constraints
Unique per (user, skill)
Validation ensures valid_until >= valid_from when both are set
Relationships
Foreign key to User
Foreign key to Skill

This is the operational relation that stores proficiency and optional certification validity windows.

Device¶

A registered mobile or web client for a user.

Fields
id UUID primary key
device_id
name
platform
app_version
last_seen_at
created_at
push_provider
push_token
notifications_enabled
timezone
Constraints
Unique per (user, device_id)
Relationships
Foreign key to User
One-to-many with DeviceSession

This model supports device-aware login, push notifications, and session visibility across mobile and web clients.

DeviceSession¶

Refresh-token-backed session tracking bound to a device.

Fields
id UUID primary key
device
refresh_jti
created_at
revoked_at
ip
user_agent
Constraints
refresh_jti is unique
Relationships
Foreign key to Device

This model allows the backend to revoke individual sessions or all sessions for a user while retaining device context.

Invite¶

Invitation used for internal-user or customer-user onboarding.

Fields
id UUID primary key
invite_type
email
org
role
token
expires_at
created_by
created_at
accepted_at
accepted_by
cancelled_at
cancelled_by
Constraints
token is unique
Relationships
Foreign key to Organization
Foreign key to User as created_by
Foreign key to User as accepted_by
Foreign key to User as cancelled_by

This model supports onboarding flows for both internal workforce users and customer-portal users.

Derived behavior¶

is_accepted
is_cancelled
is_expired
status
pending
accepted
expired
cancelled
is_valid()
Only True when status is pending

Relationship overview¶

flowchart TD
    User[User]

    UserProfile[UserProfile]
    UserSettings[UserSettings]
    UserWorkSchedule[UserWorkSchedule]
    UserWorkDay[UserWorkDay]

    Skill[Skill]
    UserSkill[UserSkill]

    Device[Device]
    DeviceSession[DeviceSession]

    Invite[Invite]
    Organization[Organization]

    User -->|1:1| UserProfile
    User -->|1:1| UserSettings
    User -->|1:1| UserWorkSchedule
    UserWorkSchedule -->|1:N| UserWorkDay

    User -->|1:N via manager| UserProfile
    User -->|1:N| UserSkill
    Skill -->|1:N| UserSkill

    User -->|1:N| Device
    Device -->|1:N| DeviceSession

    Organization -->|1:N| Invite
    User -->|created_by| Invite
    User -->|accepted_by| Invite
    User -->|cancelled_by| Invite