Nodes Subgraph

The Nodes subgraph is the canonical owner of user profiles on the Ngwenya platform. It extends the base identity provided by the auth service (which manages login credentials) into fully-featured consumer profiles with handles, social connections, privacy controls, and cross-service metadata.

Port: 3009 · Federation: Apollo v2 · Database: MongoDB (users, follows, collections, user_attributes, blocked_users collections)

Architecture

apps/nodes/src/
├── actors/user/          — User entity, mutations, federation, privacy resolvers
│   ├── user.entity.ts        — Federated User type (@key "id", @extends)
│   ├── user-mutation.resolver.ts  — Profile updates, handle claims, preferences
│   ├── user-federation.resolver.ts — __resolveReference for cross-subgraph resolution
│   ├── content-visibility.resolver.ts — contentDisplayName, contentAvatarUrl
│   ├── age-verification.resolver.ts  — Age verification status + self-declaration
│   ├── support-proxy.resolver.ts     — Pseudo-anonymous aliases, contact sharing
│   ├── admin-users.resolver.ts       — Tower-scoped user listing + search
│   ├── admin-users.service.ts        — Paginated user queries (admin)
│   ├── account-change-hook.controller.ts — TCP listener for account lifecycle events
│   ├── cookie-consent.service.ts     — GDPR cookie preferences
│   └── data-export.service.ts        — GDPR data export (JSON download)
├── attributes/           — Key-value metadata per user (cross-service)
├── blocked-users/        — User block/unblock system
├── collections/          — Wishlists and curated collections
├── follows/              — Social graph (follow/unfollow)
├── membership/           — Organization membership federation
├── murchaser-dashboard/  — Buyer-side order aggregation
└── utils/                — Shared utilities

All providers are registered in a single NodesModule. The directory structure is for code organization only.

Core Entity: User

The User entity federates from the auth service using @key(fields: "id") with @extends. The auth service owns the id field; Nodes owns everything else.

type User @key(fields: "id") @extends {
  id: ID! @external

  # Profile (owned by Nodes)
  displayName: String
  handle: String              # v|handle sigil
  bio: String
  avatarUrl: String
  location: String
  website: String
  company: String
  handleChangedAt: DateTime
  handleHistory: [HandleHistoryEntry!]!

  # Privacy-Aware Display
  contentDisplayName: String! # Computed from privacy settings
  contentAvatarUrl: String    # null when anonymous
  contentVisibilityStatus: ContentVisibility!

  # Age Verification
  isAgeVerified: Boolean!
  ageVerificationStatus: AgeVerificationStatus!

  # Support Anonymity
  supportAlias: String       # e.g. "Customer-A7B3C"
  supportContactEmail: String # Only visible if consumer explicitly shared
  supportContactPhone: String

  # Preferences
  preferences: UserPreferences!
  attributes: [UserAttribute!]!
}

Profile Auto-Creation

When auth creates a new user, it emits a user_created TCP event. The AppController in Nodes listens for this event and auto-creates the corresponding User document in MongoDB:

@EventPattern('user_created')
async handleUserCreated(data: { userId: string; email?: string }) {
  await this.userModel.create({ userId: data.userId, email: data.email });
}

If a profile query arrives before the event (race condition), the resolvers use lazy initialization — creating the profile on-demand during the first mutation.

Handle System (`v|` sigil)

Users claim a globally unique handle with the v| sigil prefix (e.g., v|sarah). The handle becomes the user's public URL slug: mallnline.com/u/sarah.

Rules

API

# Check availability
query { checkUserHandleAvailability(handle: "sarah") } # → true/false

# Claim or change handle
mutation { updateProfile(input: { handle: "sarah" }) { id handle handleChangedAt } }

Social Graph

Follows

The follow system implements a unidirectional social graph stored in the follows collection. Users can follow three target types:

# Follow
mutation { followEntity(input: { targetId: "...", targetType: MALET }) { id } }

# Unfollow
mutation { unfollowEntity(targetId: "...") }

# Query followers / following
query { followers(targetId: "...", targetType: MALET) { edges { node { id } } } }
query { following(userId: "...") { edges { node { id targetType } } } }
query { isFollowing(userId: "...", targetId: "...") } # → Boolean

Indexing: Compound unique index on (followerId, targetId) prevents duplicates. Secondary index on (followerId, targetType) powers "all Malets I follow" queries.

Collections (Wishlists)

Users create named collections to organize saved items (see Social Wishlist Collaboration for real-time synchronization and sharing architecture):

# CRUD
mutation { createCollection(input: { name: "Summer Wishlist" }) { id } }
mutation { addToCollection(collectionId: "...", itemId: "...", itemType: PRODUCT) { id } }
mutation { removeFromCollection(collectionId: "...", itemId: "...") { id } }

# Query
query { myCollections { id name itemCount items { itemId itemType } } }

Content Visibility & Privacy

The ContentVisibilityResolver computes what name and avatar to display on reviews, comments, and community content based on the user's privacy preferences:

This resolver is used by the community, reviews, Q&A, and blog comment subgraphs via federation. When those subgraphs resolve a User entity, the contentDisplayName field automatically applies the privacy mask.

Support Anonymity

The SupportProxyResolver provides pseudo-anonymous identities for support interactions:

• supportAlias — A randomly generated alias (e.g., Customer-A7B3C) scoped to a Malet/Organization. Stable across interactions with the same seller.
• supportContactEmail / supportContactPhone — Only populated if the consumer explicitly shared contact info on a specific support ticket (via ShareContactWithIssue mutation).

This ensures Malet Owners can respond to support requests without seeing the buyer's real identity unless the buyer opts in.

Age Verification

Self-declaration age verification for age-restricted products and services:

mutation { declareAge(dateOfBirth: "1990-01-15") { isAgeVerified ageVerificationStatus } }

The platform never exposes the user's actual date of birth. Only the boolean isAgeVerified and the ageVerificationStatus enum are accessible in the GraphQL schema.

Blocked Users

Users can block other users, hiding them from search results and preventing messaging:

mutation { blockUser(targetUserId: "...") { id } }
mutation { unblockUser(targetUserId: "...") }
query { blockedUsers { targetUserId blockedAt } }
query { isBlocked(targetUserId: "...") } # → Boolean

Cross-Service Dependencies

GraphQL API Reference

Queries

# Profile
user(id: ID!): User
checkUserHandleAvailability(handle: String!): Boolean!

# Social Graph
followers(targetId: ID!, targetType: FollowTargetType!, limit: Int): FollowConnection!
following(userId: ID!, limit: Int): FollowConnection!
isFollowing(userId: ID!, targetId: ID!): Boolean!
followerCount(targetId: ID!): Int!
followingCount(userId: ID!): Int!

# Collections
myCollections: [Collection!]!
collection(id: ID!): Collection

# Admin (Tower)
adminUsers(page: Int, limit: Int, search: String): UserConnection!

Mutations

# Profile
updateProfile(input: UserUpdateDTO!): User!
updatePreferences(input: UserPreferences!): User!
updatePrivacySettings(input: PrivacyPreferences!): User!
toggleProfileVisibility(visibility: VisibilityPrivacy!): User!

# Push Tokens
registerPushToken(token: String!): User!
unregisterPushToken(token: String!): User!

# Social Graph
followEntity(input: CreateFollowInput!): Follow!
unfollowEntity(targetId: ID!): Boolean!

# Collections
createCollection(input: CreateCollectionInput!): Collection!
addToCollection(collectionId: ID!, itemId: ID!, itemType: CollectionItemType!): Collection!
removeFromCollection(collectionId: ID!, itemId: ID!): Collection!
deleteCollection(id: ID!): Boolean!

# Support
shareContactWithIssue(issueId: ID!): Boolean!
revokeContactFromIssue(issueId: ID!): Boolean!

# Age Verification
declareAge(dateOfBirth: String!): User!

# Blocking
blockUser(targetUserId: ID!): UserBlock!
unblockUser(targetUserId: ID!): Boolean!

Testing

Related

• Handle System — Cross-namespace handle reservation and sigil conventions
• Social Graph Architecture — Follow System, feed algorithms, and aggregation
• Privacy & Security APIs — Cookie consent, GDPR export, session management
• Support Ticket Anonymity — Pseudo-anonymous aliases and contact sharing architecture
• User Identity Resolution — How x-user-id maps to a profile across subgraphs
• Wishlists & Collections — Collection CRUD and item management API
• Social Wishlist Collaboration — Architecture for collaborative custom lists and data synchronization.