Skip to content

Account & Group Lifecycle

This section covers the journey of a user from signup through ongoing group management, and what a user can see about their own access at any point along the way.

Lifecycle Overview

stateDiagram-v2
    [*] --> Active: Signup

    Active --> Deactivated: Deactivates
    Deactivated --> Active2: Reactivates (≤ 90 days)
    Deactivated --> [*]: 90 days elapse

    Active --> Suspended: Admin suspends
    Suspended --> Active3: Admin reinstates

    Active --> Deleted: Requests deletion
    Deleted --> [*]

    state "Active" as Active2
    state "Active" as Active3

Signup Flow

User Registration

Step 1: Google Auth

flowchart TD
    A["Sign Up with Google"] --> B[Google OAuth consent screen]
    B --> C[User grants permissions]
    C --> D["System receives: email, name, profile picture"]

Step 2: User Type Selection

The user is asked which side of the marketplace they're on: "I want to post cargo for shipment" or "I want to offer shipping capacity."

Step 3: Auto-Group Assignment

flowchart TD
    A{User selects group} -->|"I want to post cargo"| B["Create user\ngroups: [cargo_owner]"]
    A -->|"I want to offer capacity"| C["Create user\ngroups: [capacity_provider]"]

Both branches populate user_id (auto-generated), email, and name from the Google profile.

Step 4: Company Profile

The user enters business information (company name, country, city, phone, and optionally a website and description), which is attached to their profile alongside their existing group membership.

Step 5: Ready to Use

The user can now:

  • Create listings (based on their group)
  • View other listings
  • Send messages
  • (not yet) Access premium features: that requires verification

Default Group Assignment

Selection at Signup Group Assigned Key Permissions Granted
"I want to post cargo" cargo_owner Create cargo listings, read capacity listings, send messages, view assigned conversations
"I want to offer capacity" capacity_provider Create capacity listings, read cargo listings, send messages, view assigned conversations

Platform-created admin and support accounts are the exception. They're never self-signup, and are always assigned manually by an existing platform admin (see Admin User Management).

Group Management

Assigning additional groups: an admin assigns groups after verification or upgrades by pointing a user ID at a group ID. Verifying a user, for instance, is just assigning them to verified_shipper, since that group inherits from cargo_owner, the user ends up with both groups and the union of their permissions.

Removing groups: groups are removed the same way, in reverse, except the default group (cargo_owner or capacity_provider), which cannot be removed; the platform rejects that request.

Viewing user groups: a user's groups, their inherited permissions, and their overall effective permissions can all be read together for a given user. See GraphQL Implementation for the exact API calls behind assigning, removing, and viewing groups.

Verification & Upgrades

Email verification happens automatically at signup, since Google OAuth has already verified the address.

Company verification follows three steps:

  1. Initiate: the user submits their business name, registration number, VAT number, and banking details, creating a verification record in pending status
  2. Admin review: an admin reviews the submitted documents and approves, rejects, or requests more information
  3. Auto-assignment: on approval, the system automatically assigns the user to the matching verification group (verified_provider or verified_shipper), the same assignment operation an admin would trigger manually

Once verified, the user gains:

  • A "Verified" badge on their profile
  • Enhanced visibility in search
  • Access to premium features
  • Enhanced permissions

Multi-Group Scenario

flowchart LR
    A["Day 1: Signup\ngroups: [cargo_owner]"] --> B["Day 3: Company Verified\n+ verified_shipper"]
    B --> C["Day 10: Premium Upgrade\n+ premium_subscriber"]
    C --> D["Day 15: Becomes Moderator\n+ moderator"]
Day Event Groups After
1 Signs up as Cargo Owner cargo_owner
3 Admin approves company verification cargo_owner, verified_shipper
10 User subscribes to premium; admin assigns it cargo_owner, verified_shipper, premium_subscriber
15 User becomes a trusted platform moderator cargo_owner, verified_shipper, premium_subscriber, moderator

By Day 15, the user's effective permissions are the union of all four groups: cargo_owner as the base, verified_shipper and premium_subscriber each inheriting from it, and moderator contributing independently.

Your Access Summary

Every user account has its own Access Summary: the personal, per-user counterpart to the group-level tables in Groups and the Permission Matrix. It's what a user sees on their own profile/account page, and it's how they can confirm exactly what they can do and see without having to reason through group inheritance themselves.

Using the Day-15 user from the scenario above as an example, their Access Summary would show:

My Groups

Group Assigned On Assigned By Source
Cargo Owner Day 1 -- Auto (signup)
Verified Shipper Day 3 admin@travomate.cargo Manual (verification approval)
Premium Subscriber Day 10 admin@travomate.cargo Manual (upgrade)
Moderator Day 15 admin@travomate.cargo Manual (promotion)

My Effective Permissions: the same shape as the platform-wide Permission Matrix, filtered to just this user:

Resource Action Allowed Granted Via
Cargo Listing Create ✓ Cargo Owner
Capacity Listing Read ✓ Cargo Owner
Shipment Tracking (live GPS) Read ✓ Verified Shipper
Premium Analytics Read ✓ Premium Subscriber
Flagged Conversations Read / Moderate ✓ Moderator
Capacity Listing Create - (no group grants this)

My Assigned Resources

Resource Type Resource Access Level Assigned Via
Conversation conv_123 (with a capacity provider) Full Individual
Cargo Listing listing_456 (own) Full (owner) Individual
Conversation conv_789 (flagged, under moderation) Read + moderate Group (Moderator)

This is distinct from the admin-facing group management panel: the admin panel is where staff assign or remove groups for any user, while the Access Summary is a read-only, personal view each user has of their own current access.

Group Change Events

Event Trigger User Notified Via Effect
user.group_assigned Admin (or system, on verification approval) assigns a group Email, e.g. "Your account has been upgraded," listing the new features unlocked User gains the new group's permissions and visibility immediately; effective permissions recalculated
user.group_removed Admin removes a group, or a subscription ends Email, e.g. "Your subscription has ended," noting the loss of premium features User loses that group's permissions and visibility immediately; active sessions remain valid

Session Management

Sessions are evaluated per-request, not cached, so group changes take effect immediately without requiring the user to log out and back in: an admin assigns a new group, the user's very next request is evaluated with the updated permissions, and refreshing the page is enough to see any newly unlocked features.

User Deactivation

Action Who Can Trigger It Effect
Temporary deactivation The user, on their own account Cannot log in; listings remain visible (marked as from an inactive user); conversations remain visible but can't be replied to; reactivation is available any time within 90 days
Admin suspension An admin, for a violation, with a reason Cannot log in; all listings hidden; cannot send or receive messages; cannot self-reactivate, requires admin action to reinstate
Permanent deletion The user, after confirming their password User data, listings, and messages are deleted; cannot be recovered

Admin User Management

Creating admin/support users: admins create staff accounts (e.g. admin or support_agent) by supplying an email, name, password, and the groups the new account should belong to.

Viewing all users: admins can list all users, with filtering and pagination, to see each user's groups, status, and signup date.

Bulk group assignment: a group can be assigned to many users at once by supplying a list of user IDs and the target group ID, rather than assigning them one at a time.

See GraphQL Implementation for the exact API calls behind account deactivation, suspension, deletion, and admin user management.

Audit Log

Timestamp Event User Detail
2025-01-15 10:00 user.created john@company.com Groups: [cargo_owner]
2025-01-15 14:30 user.profile_completed john@company.com company_name=John's Shipping
2025-01-16 09:15 user.group_assigned john@company.com Group verified_shipper, by admin@travomate.cargo
2025-01-20 16:45 user.group_assigned john@company.com Group premium_subscriber, by system

All events are timestamped and include who made the change (user, admin, or system).