Organization & Malet Management

Configure Malets, connect domains, monitor activity, and manage billing — all from the management dashboard.

🎨 Malet Designer

Route: /{{malet}}/manage/designer
Backend: updateThemeConfig and updateLayoutConfig mutations
Data: verticalConfig(slug) query for vertical-aware presets

The Malet Designer provides a high-density, professional CAD-style environment allowing Malet Owners to customize their visual brand identity and page layout. The fixed-viewport interface uses a non-scrolling sidebar + live iframe preview architecture, with an accordion-based settings panel for managing cognitive load across many configuration options.

The sidebar features two navigation tabs: Theme and Layout. Each tab uses collapsible accordion sections with inline value summaries in the header (color dots, font names, pixel values), allowing Malet Owners to see current settings at a glance without expanding every section.

Theme Editor

The Theme tab organizes settings into six collapsible accordion sections:

1. Theme Presets

One-click preset cards that apply a complete theme configuration (colors, fonts, mode, animations, radius). Presets are grouped into two tiers:

• Vertical Presets — Dynamically generated from the malet's vertical config branding defaults via verticalConfig(slug). Only shown if the malet has a verticalType set. Includes a Light and Dark variant using the vertical's primaryColor and accentColor.
• Universal Presets — Four curated presets available to all malets:

2. Brand Colors

Interactive ColorWheelPicker with pill selectors for Primary, Secondary, Accent, and Background. The accordion header shows four inline color dot swatches reflecting current values.

3. Typography

Custom font picker dropdown that renders each option in its actual typeface (not a native <select>). Includes a specimen preview box showing heading and body text with the current selection. Supports 11 curated fonts: Inter, Roboto, Outfit, Playfair Display, Source Sans Pro, Poppins, Montserrat, Lato, Raleway, Open Sans, and DM Sans.

4. Display

Theme Mode (LIGHT / DARK / AUTO) and Animation Level (MINIMAL / STANDARD / RICH) configured via segmented radio buttons. The accordion summary shows the current values inline (e.g., "AUTO · STANDARD").

5. Border Radius

Range slider (0–64px) with live preview shape and pixel readout.

6. Advanced (Custom CSS)

Monospace textarea for custom CSS overrides with a character counter (2000 limit). Includes a warning badge alerting Malet Owners that overrides may break their Malet layout. The value is persisted via the customCSS field on ThemeConfig.

Preview Toolbar

The preview panel includes a responsive toolbar above the iframe:

Changes are reflected in real-time via cross-origin postMessage with the SYNC_PREVIEW_CONFIG payload. The preview sandbox intercepts navigation clicks and shows an "Action disabled in Preview Builder" toast.

Layout Editor

Configure which Malet sections appear and in what order. The system supports 31 slot types organized into two categories:

Core Sections (10)

Available to all malets regardless of vertical:

Vertical Widgets (21)

Specialized sections unlocked per vertical. Only the vertical matching the malet's verticalType is shown in the "Add Section" picker:

Vertical widget slots display a purple badge in the active sections list and are visually distinguished with a purple accent in the "Add Section" picker.

Layout Controls

• Drag to reorder: Grab the ⠿ handle to rearrange sections
• Toggle visibility: Click the 👁️/✕ icon to show/hide
• Custom headings: Type in the heading input to override section titles
• Remove: Hover to reveal the 🗑️ remove button
• Add Section: Open the "Add Section" accordion to browse available core and vertical-specific widgets

🌐 Custom Domains

Route: /{{malet}}/manage/settings (scroll to Custom Domains section)
Backend: addCustomDomain, verifyCustomDomain, removeCustomDomain mutations

Connect your own domain to your Malet. After adding a domain, the system provides DNS TXT record instructions for verification.

How It Works

1. Add your domain: Enter your domain name (e.g. shop.example.com) in the input field and click "Add Domain".
2. Add DNS TXT Record: Copy the provided verification details:
   • Host: _ngwenya-verify.your-domain.com
   • Value: The unique verification token shown Add this as a TXT record in your DNS provider (GoDaddy, Cloudflare, Namecheap, etc.)
3. Click Verify: Once the DNS propagates (usually 1-24 hours), click the "🔍 Verify" button. The system checks for the TXT record.
4. SSL Provisioning: After verification, an SSL certificate is automatically provisioned. Watch the cert status badge update to ACTIVE.

Domain Status Reference

📋 Team Activity Feed

Route: /orgs/{{slug}}/manage → "Activity" tab
Backend: organization.activityFeeds connection (paginated)

The Activity Feed displays a chronological timeline of all team actions within your organization. Every membership change, role update, and setting modification is logged.

Tracked Event Types

Each event displays the actor (who performed the action), the target (who was affected, if applicable), a relative timestamp ("3h ago"), and any relevant metadata (old/new role, org name, etc.).

📊 Organization Analytics

Route: /orgs/{{slug}}/manage → "Analytics" tab
Component: src/lib/components/admin/OrgAnalyticsPanel.svelte
Backend: Client-side aggregation from organizationAuditEvents + organizationTeams + membership data

The Organization Analytics tab provides Org Owners and Admins with visual insights into team activity and composition. Since the organizations subgraph has no dedicated analytics resolver, all aggregation is done client-side from existing queries.

KPI Cards

Charts & Visualizations

1. Activity Over Time — Bar chart showing daily event counts for the last 30 days
2. Role Distribution — SVG donut showing OWNER/ADMIN/MEMBER/VIEWER proportions
3. Event Type Breakdown — Horizontal colored bars showing counts per event type
4. Top Contributors — Leaderboard table with 🥇🥈🥉 medals, action count, last active
5. Teams Table — Team name, member count, scoped Malets, creation date

Data Fetching

The panel fetches data via Promise.allSettled for resilient parallel loading:

• organizationAuditEvents(orgId, limit: 200) — raw event stream
• organizationTeams(orgId) — team listing
• members — passed as prop from the parent page (already loaded)

Component Props

⚙️ Organization Settings

Route: /orgs/{{slug}}/manage → "General" tab
Backend: updateOrganization mutation with settings input

The Organization Settings page has three panels: Organization Profile, Billing Preferences, and Notification Controls.

💳 Billing Preferences

🔔 Notification Controls

💳 Organization Billing & Subscriptions

Route: /orgs/{{slug}}/billing
Backend: Future implementation in the payments and organizations subgraphs (Pending P0 Epic).

The Subscription Management page allows organization admins to upgrade their tier (Starter/Pro/Enterprise), manage payment methods, and view invoice history. As the backend infrastructure is currently in development, this frontend page operates using robust, strongly-typed mocks that mirror the intended GraphQL schema.

Feature Capabilities

• Tiers Preview: Real-time toggle between monthly/annual pricing (20% discount standard).
• Payment Methods: List verified payment methods via Stripe Setup Intents structure.
• Invoices: Downloadable PDF invoice stubs.
• Design Tokens: Extensive use of $mall tokens (var(--mall-accent), var(--mall-light-bg)) to ensure consistency with the system theme.

Mock Data Architecture

The data structures used here (Subscription, PaymentMethod, Invoice) are defined in src/routes/orgs/[slug]/billing/mockData.ts. These interface models must be directly copied when authoring the backend GraphQL schema in the Phase 2 launch.

📡 GraphQL Reference

All management features are powered by these GraphQL operations:

Mutations

updateThemeConfig(id: ID!, input: ThemeConfigInput!): Malet
updateLayoutConfig(id: ID!, input: LayoutConfigInput!): Malet
addCustomDomain(id: ID!, input: CustomDomainInput!): Malet
verifyCustomDomain(id: ID!, domain: String!): Malet
removeCustomDomain(id: ID!, domain: String!): Malet
updateOrganization(input: UpdateOrganizationInput!): Organization
# input.settings contains:
#   billing: { currency, taxId, billingEmail }
#   notifications: { lowStockAlerts, newOrderNotifications, payoutNotifications }

Queries (Activity Feed)

query GetOrgActivityFeed($orgId: ID!, $first: Int, $after: String) {
	organization(id: $orgId) {
		activityFeeds(first: $first, after: $after) {
			edges {
				node {
					id
					eventType
					actorId
					targetUserId
					metadata
					createdAt
				}
			}
			pageInfo {
				hasNextPage
				endCursor
			}
		}
	}
}

🔄 Org Context Switcher

Component: src/lib/components/OrgSwitcher.svelte
Store: src/stores/orgs.ts
Utilities: src/lib/utils/orgContextUtils.ts

The Org Context Switcher allows authenticated users with organization memberships to toggle between personal and organization scoped contexts. All subsequent GraphQL requests include the x-org-id header so that downstream subgraphs resolve permissions, data, and activity within the correct org boundary.

Architecture

OrgSwitcher.svelte (UI)
  ↓ selectOrg(id)
orgsStore.switchContext(id) (atomic state transition)
  ↓ sets isSwitching=true ← localStorage flag: ngwenya_org_switching
  ↓ updates currentOrgId in localStorage + store
  ↓ returns { success, orgName }
  ↓ isSwitching=false (after 500ms drain window)
goto('/lobby') → invalidateAll()
  ↓ SvelteKit re-runs load() functions
client.ts headers() → reads localStorage('currentOrgId')
  ↓ sends x-org-id header
Gateway auth.context.ts → validateMembership(orgId, userId)
  ↓ sets ctx.orgId if valid

401 Suppression During Switch

When switching contexts, stale in-flight requests from the previous page may hit org-scoped guards and receive 401 responses. The client.ts response middleware reads a ngwenya_org_switching localStorage flag (set by orgsStore.switchContext) to suppress session-expiry handling during the transition window (500ms).

Without this fix, the response middleware would interpret the 401 as a session expiry, logout the user, and redirect to /auth.

Utility Functions

Component Props

OrgSwitcher takes no props. It reads from derived stores:

Data Attributes (E2E)

📂 File Reference

Related

• Organizations & Permissions — Backend subgraph powering memberships, roles, and the permission system
• Teams & Sub-Groups — Group org members into named teams with LEAD/MEMBER roles
• Custom RBAC — Admin-defined custom roles with configurable permission matrices
• Edit History Audit Trail — Cross-entity field-level change tracking and maletActivityFeed
• Settings Architecture — Frontend settings page structure for user preferences, security, and privacy
• Tag Registry — Platform-managed curated tags that Malet Owners assign to their storefronts
• Professional Services & Client Portals — Client engagement portals and document vaults for professional Malets
• Wellness & Beauty — Membership plans, practitioner booking, and client wellness profiles for spa and beauty Malets
• Revenue Sharing & Payouts — Commission splitting, Stripe Connect onboarding, and the Malet Owner earnings dashboard
• Org Context & Tier Access — The complete x-org-id header pipeline, canCreateOrganization() gate, search scoping, and org UX layer
• Advanced Audit Logging UI — Upgraded Audit Log with client-side filtering, CSV/JSON export, and SIEM webhook management
• Permission Matrix Editor — Interactive checkbox matrix for composing custom role permissions
• Workspaces & The Tower — Admin dashboard workspace and Organization Analytics tab architecture
• User Guide: Designing Your Malet Storefront — End-user guide covering the Designer UI from the Malet Owner perspective