Asset management user experience - Architecture patterns

Problem statement

Traditional financial platforms fracture user experiences across disparate systems. KYC portals, custody platforms, compliance dashboards, and investor portals rarely share data models or authentication. This fragmentation creates operational friction:

• Investors check balances in one system, claim yields in another, verify identity in a third
• Compliance officers manually reconcile data between systems to answer regulatory inquiries
• Issuers manage investor onboarding pipelines through disconnected tools
• Administrators lack unified observability into platform health

The Asset Tokenization Kit addresses this by anchoring all personas to unified identity and on-chain asset state, eliminating synchronization overhead.

Target audience

This document is for product engineers and architects building asset tokenization platforms. It explains:

• How state management patterns reconcile blockchain finality with responsive UX
• Why accessibility features reduce operational risk in high-stakes financial interfaces
• How persona-specific observability surfaces actionable metrics without information overload

Not covered here: Step-by-step implementation guides (see user guides), detailed API references (see smart contract documentation), or deployment instructions (see infrastructure documentation).

Key concepts

Unified identity as coordination primitive

All personas—investors, issuers, compliance officers, administrators—authenticate through a single identity system backed by OnchainID contracts. When an investor completes KYC, compliance officers see the signed claim immediately. When issuers schedule coupon payments, observability dashboards update in real-time. This architecture eliminates race conditions inherent in multi-database systems.

Atomic settlement reduces state complexity

Traditional platforms maintain complex state machines tracking escrow periods, settlement windows, and custody transfers. The Kit's delivery-versus-payment (DvP) mechanism collapses this to atomic transactions: compliance checks, payment, and token delivery happen in a single block, eliminating intermediate states that require manual reconciliation.

Observability as user-facing feature

Rather than treating metrics as internal-only infrastructure, the Kit exposes filtered observability data to each persona:

• Investors see transaction history with gas costs and block explorer links
• Issuers see holder distribution, yield claim rates, and compliance rejection reasons
• Compliance officers see KYC pipeline metrics and expiring identity claims
• Administrators see gas cost trends and infrastructure health

This selective disclosure prevents information overload while maintaining audit transparency.

Architecture overview

Before diving into specific persona journeys, understanding how personas interact with core platform components helps contextualize the detailed workflows that follow.

This high-level view shows how unified identity coordinates all personas, compliance engine enforces rules consistently, asset contracts execute tokenization logic, and observability provides role-filtered visibility. Each persona section below details specific workflows within this architecture.

Core architectural principles:

• Single identity source: All personas authenticate through OnchainID contracts, eliminating synchronization gaps between systems
• Compliance by design: Modular compliance rules evaluate before every operation, embedding regulatory requirements in protocol logic
• Persona-filtered observability: Observability stack exposes metrics relevant to each role, preventing information overload while maintaining audit transparency

State management philosophy

The Kit treats blockchain as the source of truth for asset state and PostgreSQL as a query-optimized cache. TanStack Query manages this dual-state architecture:

Cache-first queries (for latency-tolerant reads):

const { data: balance } = orpc.token.balance.useQuery({
  tokenAddress: "0xABC...",
  holderAddress: "0x123...",
});

The ORPC procedure checks database cache first (responds in <10ms). If cache is fresh (<30 seconds), query returns immediately. If stale, procedure queries blockchain RPC, updates cache, returns authoritative balance.

Cache-bypass queries (for compliance-critical reads): Compliance checks query blockchain directly, bypassing cache, to ensure transfer eligibility verification uses real-time state.

The 30-second staleness threshold is tunable per query type. This selective freshness prevents both slow experiences (over-fetching blockchain) and compliance failures (stale cache).

Component hierarchy and data fetching

The token dashboard (/token/$factoryAddress/$tokenAddress/) splits into tabs: Overview, Holders, Events, Compliance, Yield, Permissions. Each tab is a separate route with independent data requirements.

Root layout fetches shared metadata once:

const { data: token } = orpc.token.metadata.useQuery({
  address: tokenAddress,
});

Child routes access cached metadata without refetching, reducing backend load. Without shared cache, navigating between tabs would trigger redundant fetches.

Real-time updates via subgraph subscriptions

Observability dashboards use GraphQL subscriptions for live transaction counts. The Graph indexer listens to blockchain events (Transfer, Mint, Burn) and pushes updates via WebSocket:

const { data: events } = useSubscription({
  query: gql`
    subscription RecentTransfers($tokenAddress: String!) {
      transfers(
        where: { token: $tokenAddress }
        orderBy: timestamp
        orderDirection: desc
        first: 50
      ) {
        id
        from
        to
        value
        timestamp
      }
    }
  `,
  variables: { tokenAddress: "0xABC..." },
});

When transfer confirms on-chain, all connected dashboards update within 2-3 seconds. This reduces query load by 99.9% versus polling (10 pushes/day vs 7,200 polls/hour per client).

Form state and optimistic updates

When scheduling coupon payments, forms use TanStack Form for instant validation feedback. Mutations execute optimistically:

1. UI immediately adds scheduled distribution with "Pending" badge
2. ORPC procedure submits blockchain transaction
3. Transaction confirms after 30 seconds
4. TanStack Query invalidates cache, refetches data
5. "Pending" badge changes to "Scheduled"

If transaction fails, optimistic update rolls back with error toast. This makes UI feel instant while maintaining consistency with blockchain state.

Implementation reference: See kit/dapp/src/lib/query/optimistic-mutations.ts (if available) for rollback patterns, or examine TanStack Query cache invalidation in ORPC mutation procedures.

Responsive design strategy

Why mobile-first matters

Institutional investors increasingly expect consumer-grade mobile experiences. A CFO reviewing bond holdings during a board meeting should see identical data as their desktop dashboard. Mobile-first design forces ruthless prioritization—only essential information fits above fold. This discipline improves desktop layouts by eliminating clutter.

Breakpoint strategy

Components use Tailwind responsive utilities:

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  {/* Mobile: stacked, Desktop: 3-column grid */}
</div>

Touch-friendly controls

Mobile components enforce 44px minimum tap targets (Apple HIG standard). Buttons smaller than 44px create misclick frustration:

<Button className="min-h-[44px] min-w-[44px] touch-manipulation">
  Claim €150
</Button>

The touch-manipulation CSS property disables double-tap zoom on buttons, preventing accidental zooms.

Form inputs use 16px minimum font size to prevent iOS auto-zoom. When inputs use <16px font, iOS zooms the page to make text readable, disorienting users.

Progressive disclosure

Token dashboard has 6 tabs on desktop. On mobile, tabs don't fit horizontally. Mobile layout uses dropdown selector:

Mobile: [Dashboard Menu ▼] opens full-screen menu with tab list

Desktop: [Overview] [Holders] [Events] [Compliance] [Yield] [Permissions] all visible

This pattern extends to complex forms. Bond deployment wizard shows one section at a time on mobile (swipe navigation). Desktop shows all sections with progress sidebar.

Accessibility architecture

Accessibility features reduce operational risk in high-stakes financial interfaces. Misclicks transfer thousands of dollars; missed deadlines incur penalties.

Why accessibility matters operationally

• Keyboard navigation: Treasury operators batch-process distributions without mouse fatigue during month-end close (50+ transactions in one session)
• High-contrast modes: Prevent costly misclicks when reviewing transactions in bright sunlight or dim late-night office lighting
• Screen reader compatibility: Compliance officers audit transaction logs while visually impaired or reviewing printed documents

These features also future-proof platforms. As users age, presbyopia and reduced color perception become common. High-contrast text and scalable fonts delay need for assistive technology.

Keyboard navigation patterns

Every interactive element is keyboard-accessible. Tab order follows logical reading order (top-to-bottom, left-to-right).

Focus indicators use 3px solid border with high contrast:

:focus-visible {
  outline: 3px solid hsl(var(--primary));
  outline-offset: 2px;
}

The :focus-visible pseudo-class shows outlines only for keyboard focus, not mouse clicks.

Custom components implement ARIA keyboard patterns. Token dashboard tabs use arrow key navigation:

• Tab key enters tab list
• Right/Left arrows move between tabs
• Home/End jump to first/last tab

Modal dialogs trap focus—Tab cycles through modal controls, never escaping to background. Escape closes modal.

Screen reader optimization

Semantic HTML conveys document structure:

<nav aria-label="Main navigation">
  <ul>
    <li><a href="/dashboard">Dashboard</a></li>
    <li><a href="/assets">Assets</a></li>
  </ul>
</nav>

<main>
  <h1>Token Dashboard</h1>
  <section aria-labelledby="overview-heading">
    <h2 id="overview-heading">Overview</h2>
  </section>
</main>

Icons always have text alternatives:

<button aria-label="Claim €150 yield payment">
  <CoinsIcon aria-hidden="true" />
  <span className="sr-only">Claim €150 yield payment</span>
</button>

Form validation errors announce immediately:

<input
  type="text"
  aria-label="Token symbol"
  aria-invalid={errors.symbol ? "true" : "false"}
  aria-describedby="symbol-error"
/>;
{
  errors.symbol && (
    <span id="symbol-error" role="alert">
      {errors.symbol}
    </span>
  );
}

The role="alert" triggers screen reader announcement without requiring navigation.

Visual accessibility

Text meets WCAG AA contrast ratios:

• Normal text (16px): 4.5:1 minimum
• Large text (24px): 3:1 minimum
• UI controls: 3:1 minimum

Color is never sole indicator. Status badges use color + text:

<Badge variant="success">
  <CheckIcon aria-hidden="true" />
  Approved
</Badge>
<Badge variant="error">
  <XIcon aria-hidden="true" />
  Rejected
</Badge>

Charts use patterns in addition to color:

• Line charts: Solid, dashed, dotted lines (not just colors)
• Bar charts: Hatching patterns (diagonal lines, dots, fills)

This ensures readability for users with deuteranopia (red-green colorblindness, 8% of men).

Persona-specific observability

Each persona sees filtered metrics relevant to their role, preventing information overload while maintaining audit transparency.

Note: This section provides architectural context for persona-driven observability. For step-by-step operational procedures, example data, and troubleshooting workflows specific to each role, refer to the user guides. Separating high-level architecture from detailed procedures keeps this document focused on system design patterns for engineering audiences.

Investor observability

Portfolio dashboard shows:

• Transaction history: Last 50 transactions with timestamps, amounts, gas fees, block explorer links
• Yield accrual chart: Daily interest visualization
• Compliance status: "Your identity: Verified – Eligible for 8 asset classes"

Each transaction row expands to show hash, gas fee, block number, contract interaction details. This builds trust—investors independently verify on blockchain without trusting platform data.

Related: See Identity & compliance architecture for how OnchainID claims determine asset class eligibility, and Observability stack for metrics collection patterns powering these dashboards.

Issuer observability

Bond dashboard shows:

• Holder metrics: Investor count, geographic distribution (pie chart), average holding size
• Yield metrics: Average claim time, claim rate after 30 days, unclaimed amounts
• Gas tracking: Total gas spent, breakdown by operation type
• Compliance events: Transfer rejection rate, rejection reasons

Example scenario: Average claim time of 8.2 days suggests engaged investors. If it drifts to 30+ days, issuer investigates communication gaps or UX friction.

Compliance rejection rate of 0.8% indicates rules work without blocking legitimate activity. If it spikes to 10%, issuer reviews rule configurations for errors.

Related: Compliance control plane explains modular compliance architecture and rule orchestration. Observability metrics details dashboard configuration and alert thresholds.

Compliance officer observability

Compliance dashboard shows:

• KYC pipeline: Application volume (pending/approved/rejected), average review time, approval rate
• Identity health: Expiring claims (investors with documents expiring <30 days), revoked claims
• Sanctions alerts: Real-time OFAC/EU sanctions list updates, match status in investor base
• Transfer monitoring: Real-time feed of transfer attempts (successful/rejected), filtering by rejection reason

Expiring claims metric enables proactive outreach before documents expire: "Your passport expires in 20 days. Please re-verify identity to maintain eligibility."

Real-time transfer feed flags specific compliance rules blocking transfers for immediate investigation.

Related: Identity registry explains claim issuance and expiration tracking. KYC workflow management details application processing and claim automation.

Administrator observability

Admin dashboard shows:

• System health: RPC endpoint latency, database query performance (p95), subgraph indexing lag
• Gas trends: 7-day moving average, cost per operation type, anomaly detection (alerts if daily cost exceeds threshold)
• User activity: Daily active users, new registrations, KYC approval rate, asset deployment rate
• Asset health: Total assets deployed, total investors, total value locked, assets with <10 investors (flagged for review)

RPC latency spikes to 500ms trigger infrastructure investigation. Gas anomaly detection prevents runaway spending (e.g., accidental mass OnchainID deployments burning budget).

"Assets with <10 investors" metric identifies struggling issuances for proactive issuer outreach.

Related: Observability architecture explains VictoriaMetrics, Loki, and Tempo integration. System health dashboards details alert hierarchy and incident response workflows.

User flow patterns

Investor subscription flow

Flow summary: Investors authenticate, complete KYC verification, pass eligibility checks, fund wallets, and execute atomic DvP settlements that deliver tokens instantly—eliminating multi-day escrow periods inherent in traditional finance.

Critical architectural moments:

1. Identity verification gate: UI prevents viewing investment opportunities without KYC completion. This enforces compliance by design—UI blocks non-compliant actions rather than rejecting post-attempt.

2. Eligibility check: System validates OnchainID claims against bond requirements before showing subscribe button. Ineligible investors see clear message: "This asset requires Accredited Investor status."

3. Atomic DvP settlement: Payment and token delivery happen in single transaction—no escrow period, no settlement risk. Traditional platforms take 1-3 days; here settlement is instant.

Issuer asset creation flow

Flow summary: Issuers configure asset parameters through guided wizard steps, validate gas costs before deployment, assign operational roles post-deployment, and fund yield mechanisms—creating production-ready assets in minutes rather than weeks.

Key design decisions:

1. Wizard prevents misconfiguration: Each step validates inputs before allowing progression. UI blocks invalid ISIN formats or negative coupon rates at data entry time, not transaction submission.

2. Gas estimation provides cost transparency: Before deploying, issuer sees estimated cost based on current network conditions. If gas spikes during congestion, issuer can delay deployment.

3. Post-deployment checklist: Success screen shows required next steps (assign roles, fund yield wallet) rather than leaving issuer to discover through trial-and-error. Reduces support tickets.

Compliance officer identity approval flow

Flow summary: Compliance officers leverage automated sanctions screening and document OCR to triage applications, review flagged cases manually, and issue cryptographically-signed OnchainID claims that unlock immediate platform access—reducing approval cycles from days to hours.

Operational efficiency highlights:

1. Automated checks reduce workload: Sanctions screening and document OCR run instantly. Officer only reviews cases flagged by automation—doesn't manually search OFAC lists.

2. Risk-based prioritization: High-risk applications (sanctions matches, suspicious patterns) bubble to queue top. Critical cases reviewed first.

3. Audit trail enforcement: Every approval/rejection logs officer wallet address and timestamp. If regulators question why investor was approved, system shows exactly who approved, when, and what documents were reviewed.

Technical implementation notes

Component library: Radix UI primitives

Kit uses Radix UI for accessible components. Radix provides unstyled primitives (dialogs, dropdowns, tooltips) with ARIA attributes and keyboard interactions built-in.

Example: Compliance rule builder uses Radix Accordion:

<Accordion type="multiple">
  <AccordionItem value="country-restrictions">
    <AccordionTrigger>Geographic restrictions</AccordionTrigger>
    <AccordionContent>
      {/* Country allow-list/block-list form fields */}
    </AccordionContent>
  </AccordionItem>
  <AccordionItem value="investor-caps">
    <AccordionTrigger>Investor caps</AccordionTrigger>
    <AccordionContent>
      {/* Max holder count, max allocation fields */}
    </AccordionContent>
  </AccordionItem>
</Accordion>

Radix automatically adds:

• role="region" on expandable sections
• aria-expanded="true" when section is open
• Keyboard controls: Enter/Space to toggle, Tab to move between sections
• Focus management: When opening section, focus moves to first interactive element

Implementation reference: See kit/dapp/src/components/ui/accordion.tsx for Radix wrapper patterns demonstrating focus management and keyboard controls.

Mobile wallet integration

Mobile investors need seamless transaction signing. Kit uses WalletConnect v2 for cross-app communication:

1. User taps "Subscribe" on mobile browser
2. Web app generates WalletConnect QR code
3. Mobile wallet scans QR (or deep link opens wallet)
4. Wallet prompts for approval
5. User approves in wallet
6. Web app receives confirmation via WalletConnect bridge

Deep linking improves this flow. Instead of QR scanning, web app detects mobile browser and uses custom URI:

if (isMobileDevice) {
  window.location.href = `metamask://wc?uri=${encodeURIComponent(wcUri)}`;
}

This opens MetaMask directly with transaction pre-loaded, reducing friction from 5 steps to 2.

Implementation reference: Wallet connection logic resides in authentication middleware and user wallet components. See kit/dapp/src/orpc/middlewares/auth/wallet.middleware.ts for authentication validation patterns.

Real-time GraphQL subscriptions

Observability dashboard uses GraphQL subscriptions over WebSocket. The Graph provides persistent connection:

const wsClient = createClient({
  url: "wss://api.thegraph.com/subgraphs/name/asset-tokenization-kit",
});

const unsubscribe = wsClient.subscribe(
  {
    query: `subscription OnTransfer($tokenAddress: String!) { ... }`,
    variables: { tokenAddress: "0xABC..." },
  },
  {
    next: (data) => {
      queryClient.setQueryData(["token.transfers"], (old) => [data, ...old]);
    },
    error: (err) => console.error("Subscription error:", err),
  }
);

When transfer confirms on-chain, indexer pushes update to subscribed clients within 2-3 seconds. Dashboard updates automatically without polling.

This scales efficiently: 1,000 connected users generate 1,000 persistent WebSocket connections but server only sends updates when events occur. Compare to polling (720,000 requests/hour even during idle periods).

Implementation reference: See kit/subgraph/src/mappings/token.ts for event handlers showing how Transfer, Mint, and Burn events update indexed state for subscription queries.

Trade-offs and design decisions

Cache staleness vs consistency

Decision: 30-second cache staleness for balance queries, real-time for compliance checks.

Rationale: Investors checking holdings don't need sub-second accuracy. Stale cache delivers <10ms response. Compliance checks require real-time blockchain queries to prevent rule violations. Selective freshness balances UX and correctness.

Alternative considered: Always query blockchain. Rejected due to 500ms+ latency degrading UX.

Optimistic updates vs guaranteed consistency

Decision: Optimistic updates with rollback for mutations.

Rationale: Makes UI feel instant (no 30-second wait for confirmation). If transaction fails, UI rolls back to previous state with error message. Users experience responsive interface without sacrificing eventual consistency.

Alternative considered: Wait for blockchain confirmation before UI update. Rejected due to poor perceived performance.

Mobile-first vs desktop-first

Decision: Mobile-first responsive design with progressive enhancement for desktop.

Rationale: Forces ruthless prioritization of essential information. Constraints of small screens eliminate clutter. Desktop layouts benefit from same discipline with bonus screen real estate for advanced controls.

Alternative considered: Separate mobile app. Rejected due to maintenance overhead (two codebases drift out of sync).

Persona-specific dashboards vs unified interface

Decision: Separate observability dashboards per persona (investor/issuer/compliance/admin).

Rationale: Each persona requires different metrics. Unified dashboard creates information overload. Filtered views prevent cognitive load while maintaining audit transparency through drill-down capabilities.

Alternative considered: Single dashboard with role-based filtering. Rejected because filtering logic complexity exceeded benefit of unified interface.

Related documentation

Core architecture references

• Identity & compliance contracts - OnchainID protocol, ERC-3643 standard, and compliance module implementation
• Compliance control plane - Unified identity verification and compliance orchestration across API and smart contract layers
• Observability & disaster recovery - Integrated monitoring stack, persona-filtered dashboards, and recovery procedures

Operational guides

• Getting started guide - End-to-end platform setup and first asset deployment
• Asset issuance workflows - Step-by-step procedures for deploying bonds, equities, funds, deposits, and stablecoins
• Operations management - Investor onboarding, compliance configuration, and corporate actions

Technical implementation

• Backend API architecture - ORPC procedures, middleware patterns, and authentication flows
• Database model - Schema design for KYC applications, user accounts, and audit logs
• Smart contract reference - Complete contract API documentation with function signatures and events

For detailed persona workflows with example data and step-by-step procedures, see the user guides section. This architecture document focuses on system design patterns and technical trade-offs for engineering audiences.