Uconf: User Configuration Service

Overview

Uconf (User Configuration) is responsible for storing user-specific configuration data that is not directory information. While Facebox stores directory information like user profiles and organization memberships, Uconf stores highly user-specific preferences and settings.

This is the first Pivot service to use DynamoDB as its primary data store, implementing a key-value store interface pattern that allows for potential future pluggability with other KV stores.

Architecture

Uconf uses a single-table design in DynamoDB with the following key structure:

• Partition Key (pk): User ID
• Sort Key (sk): Configuration type and subject identifier

This design allows efficient querying of all configuration for a given user while maintaining uniqueness constraints per configuration type and subject.

Key-Value Store Interface

Uconf implements a KV store interface with a DynamoDB implementation using github.com/guregu/dynamo.

The datastore is selected via the UCONF_DATASTORE environment variable (currently dynamodb).

API

Uconf provides three primary gRPC methods exposed through the Friend service:

1. SyncUserConfig: Returns all user configuration for a given user
2. UpsertUserConfig: Creates or updates a user configuration item (idempotent)
3. DeleteUserConfig: Removes a user configuration item

All operations are scoped to the authenticated user's principal ID for security.

Configuration Types

Sidebar Favorites

User's favorited items in the main sidebar. Can reference:

• Block ID (pages, assignments, etc.)
• Space ID

Sort key pattern: SIDEBAR_FAV#BLOCK#<blockId> or SIDEBAR_FAV#SPACE#<spaceId>

Room Sidebar Favorites

User's favorited rooms in the room sidebar.

Sort key pattern: ROOM_SIDEBAR_FAV#ROOM#<roomId>

Room Sidebar Hide Configuration

User preferences for hiding rooms or sections in the room sidebar. Can hide:

• Specific room by ID
• Entire section (favorites, directs, groups, space rooms)
• Rooms by space label

Sort key patterns:

• ROOM_HIDE#ROOM#<roomId>
• ROOM_HIDE#SECTION#<section>
• ROOM_HIDE#SPACE_LABEL#<label>

Welcome Flow Complete

Boolean flag indicating user has completed the welcome flow. Only stored when true; absence indicates false.

Sort key pattern: WELCOME#1

NATS

Publication

N/A - Uconf does not currently publish to NATS.

Consumption

N/A - Uconf does not currently consume from NATS.

Databases

Uconf uses DynamoDB with a single table design:

• Table Name: pivot-{environment}-uconf
• Billing Mode: Pay-per-request (on-demand)
• Encryption: Server-side encryption with KMS
• Point-in-time Recovery: Enabled
• VPC Access: Via DynamoDB Gateway VPC endpoint (no NAT gateway costs)

Temporal Workflows

N/A

Deployment

Uconf is a stateless service deployed via ECS Fargate with DynamoDB table access via IAM role.

Observability

Uconf uses standard Pivot observability:

• Logs forwarded to Axiom via Fluent Bit
• Traces sent to Axiom via OTEL collector
• Health check endpoint at /health

Security

Uconf is only accessible inside the VPC via Service Connect.

All operations are automatically scoped to the authenticated user's principal ID extracted from the request context. Users can only read, create, update, or delete their own configuration.

Client Resolution

Clients are responsible for resolving IDs to full objects:

• Block IDs → Block details (via Blockhead)
• Space IDs → Space details (via Blockhead)
• Room IDs → Room details (via Messenger)

Uconf returns only the raw IDs to avoid unnecessary service-to-service calls and to allow clients to leverage their existing caching mechanisms.