User Studio

User data hub at https://studio.ravenhelm.dev.

Overview

User Studio is the central hub for all user-specific data in the RavenmaskOS ecosystem. It provides:

User Directory: Centralized user profiles and directory management
Case Management: Issue tracking and case management system
Memory Management: Norns episodic memory viewer and management (future: editing)
Channel Preferences: User communication channel settings and preferences
User Self-Service Portal: End-user interface for profile management and support
RBAC Administration: Role-based access control and permissions management

Built with Next.js 16, React 19, and integrated with Zitadel SSO.

Vision: The User Data Hub

User Studio will become the single source of truth for all user-specific information:

Data Type	Current	Future
Demographics	View/Edit profiles	Enhanced profile fields
Documents	RAG document management	Document versioning, categories
Phone Numbers	Registry with verification	Auto-verification workflows
Memory	View episodic memory	Edit, delete, categorize memories
Channel Preferences	Planned	SMS/Voice/Email preferences per user
Notification Settings	Planned	Alert thresholds, quiet hours
Agent Interactions	Planned	Conversation history, feedback
Consent Management	Planned	HIPAA/privacy consent tracking

Quick Links

Resource	URL
Production	https://studio.ravenhelm.dev
Health Check	https://studio.ravenhelm.dev/api/health
Auth Provider	https://auth.ravenhelm.dev
GitLab Repo	https://gitlab.ravenhelm.dev/nwalker85/user-studio

Current Routes

User Directory (v1.2)

Route	Description
`/users`	User directory with search, filter, sort, pagination
`/users/[id]`	User profile with demographics, emergency contact
`/users/[id]/documents`	User document management with RAG status
`/users/[id]/phones`	Phone registry with verification status
`/users/[id]/memory`	Norns episodic memory viewer

Case Management (v1.3)

Route	Description
`/cases`	Case list with search, status/priority filters, stats
`/cases/new`	Create new case with user, category, priority, assignee
`/cases/[id]`	Case detail with timeline, comments, status updates

Architecture

                    Traefik (TLS)
                         │
    studio.ravenhelm.dev │
         │               │
    ┌────┴────────┐ ┌────┴────────┐   ┌─────────────┐
    │    User     │ │ PostgreSQL  │   │ Zitadel SSO │
    │   Studio    ├─┤ ravenmaskos │◄──┤   (OIDC)    │
    │  (Next.js)  │ └─────────────┘   └─────────────┘
    └─────────────┘

Tech Stack

Component	Technology
Framework	Next.js 16 (App Router, Turbopack)
UI Library	React 19
Styling	Tailwind CSS v4
Authentication	Auth.js (NextAuth v5 beta)
Database	PostgreSQL (ravenmaskos)
SSO Provider	Zitadel OIDC

Repository

GitLab: https://gitlab.ravenhelm.dev/nwalker85/user-studio

user-studio/
├── apps/
│   ├── studio/          # Next.js 16 UI
│   │   ├── app/         # App Router pages
│   │   ├── lib/         # Shared utilities (db.ts)
│   │   ├── auth.ts      # NextAuth config
│   │   └── middleware.ts
│   └── api/             # API service (placeholder)
├── migrations/          # SQL migrations
├── docker-compose.yml
└── pnpm-workspace.yaml

Deployment

Property	Value
Container	`agent-studio`
Host	odin (100.115.101.81)
Path	`/Users/ravenhelm/ravenhelm/services/agent-studio/`
Network	`ravenhelm_net`
Port	3000 (internal)

Traefik Config

/Users/ravenhelm/ravenhelm/data/traefik/config/dynamic/agent-studio.yml

Environment Variables

In /Users/ravenhelm/ravenhelm/secrets/.env:

Variable	Purpose
`AUTH_SECRET`	NextAuth session encryption
`AUTH_ZITADEL_ID`	Zitadel client ID (354196188997615651)
`AUTH_ZITADEL_SECRET`	Zitadel client secret
`DATABASE_URL`	PostgreSQL connection (URL-encoded)

Database Schema

User Directory

-- users: Core user records (synced from Zitadel)
-- user_profiles: Extended demographics, emergency contacts
-- user_phone_numbers: Phone registry with verification status
-- user_documents: RAG document metadata

Case Management

-- portal_cases: Case records with status, priority, assignment
-- portal_case_comments: Timeline comments (internal/external)

Future Tables

-- user_channel_preferences: SMS/Voice/Email preferences
-- user_notification_settings: Alert thresholds, quiet hours
-- user_consent_records: HIPAA/privacy consent tracking

Operations

# Start
ssh ravenhelm@100.115.101.81 "cd ~/ravenhelm/services/agent-studio && docker compose up -d"

# Rebuild
ssh ravenhelm@100.115.101.81 "cd ~/ravenhelm/services/agent-studio && docker compose build --no-cache studio && docker compose up -d"

# Logs
ssh ravenhelm@100.115.101.81 "docker logs -f agent-studio"

# Health check
curl https://studio.ravenhelm.dev/api/health

# Pull latest from GitLab
ssh ravenhelm@100.115.101.81 "cd ~/ravenhelm/services/agent-studio && git pull"

Troubleshooting

DATABASE_URL Special Characters

Critical: The pg library uses JavaScript's URL parser for connection strings. Passwords containing special characters must be URL-encoded:

Character	Encoded
`/`	`%2F`
`=`	`%3D`
`@`	`%40`
`#`	`%23`
`?`	`%3F`

Example:

# Wrong (will cause "searchParams" errors)
DATABASE_URL=postgresql://user:pass/word=@host:5432/db

# Correct
DATABASE_URL=postgresql://user:pass%2Fword%3D@host:5432/db

To URL-encode a password:

python3 -c "import urllib.parse; print(urllib.parse.quote('your-password', safe=''))"

Auth Issues

SSO Login Fails: Verify AUTH_ZITADEL_ID matches the Zitadel app client ID
Redirect Loop: Check AUTH_SECRET is set and matches across restarts
Session Not Persisting: Ensure cookies are set for correct domain

Roadmap

Phase	Status	Description
v1.1 Foundation	Done	Auth, routing, health check
v1.2 User Directory	Done	Profiles, documents, phones, memory viewer
v1.3 Case Management	Done	Cases, timeline, comments
v1.4 Channel Preferences	Next	User communication preferences (SMS/Voice/Email)
v1.5 Memory Management	Planned	Edit/delete/categorize episodic memories
v2 Self-Service Portal	Planned	User-facing portal at portal.ravenhelm.dev
v3 RBAC Administration	Planned	Roles, permissions, audit logs

v1.4 Channel Preferences (Next)

Enable per-user communication channel settings:

Preferred contact method (SMS, Voice, Email)
Opt-in/opt-out per channel
Quiet hours / Do Not Disturb windows
Language preferences
Notification frequency settings

v1.5 Memory Management

Enhance the episodic memory interface:

Edit memory content and metadata
Delete memories (with audit trail)
Categorize memories (personal, medical, preferences)
Memory importance scoring
Memory search and filtering

v2 Self-Service Portal

A separate user-facing interface (portal.ravenhelm.dev):

Profile viewing and updates
Case submission and tracking
Document uploads
Preference management
Communication history

Last Updated: 2026-01-05 Version: v1.3 Case Management Maintainer: Nate Walker

Overview​

Vision: The User Data Hub​

Quick Links​

Current Routes​

User Directory (v1.2)​

Case Management (v1.3)​

Architecture​

Tech Stack​

Repository​

Deployment​

Traefik Config​

Environment Variables​

Database Schema​

User Directory​

Case Management​

Future Tables​

Operations​

Troubleshooting​

DATABASE_URL Special Characters​

Auth Issues​

Roadmap​

v1.4 Channel Preferences (Next)​

v1.5 Memory Management​

v2 Self-Service Portal​