Skip to main content

Asset360 Frontend Implementation Plan

Version: 1.1
Date: October 2025
Status: In Progress

Overview​

This document outlines the comprehensive implementation plan for the Asset360 v3 frontend, leveraging existing backend infrastructure with modern Tanstack Router and TRPC v11 patterns. The plan follows KISS and YAGNI principles while building upon our sophisticated authentication and authorization system.

Research Findings​

TRPC v11 New Patterns (2024)​

  • ✅ New TanStack Query Integration: Uses queryOptions() and mutationOptions() instead of wrapped hooks
  • ✅ More React-Native: Direct use of useQuery and useMutation from TanStack Query
  • ✅ Better Type Safety: Native TanStack Query interfaces with full type inference
  • ✅ Simplified API: Less abstraction, more familiar to TanStack Query users

Tanstack Router Production Patterns​

  • ✅ File-Based Routing: Structure follows URL structure for easy navigation
  • ✅ Data Loaders: Use loaders for page-level data, suspense queries for component data
  • ✅ Suspense-First: Components focus on happy path, router handles loading/errors
  • ✅ Type-Safe Navigation: Full type safety for routes and parameters

Current State Analysis​

Backend Strengths​

  • ✅ Complete DDD architecture with domain services
  • ✅ TRPC v11 setup with schemas for all domains
  • ✅ Use cases for key workflows (SetupFund, PurchaseUnits, RunEndOfDay)
  • ✅ Authentication system with OAuth2
  • ✅ Comprehensive test coverage
  • ✅ Sophisticated middleware system (auth, roles, tenant)

Frontend Current State​

  • ✅ Role-based layout with TanStack Router navigation
  • ✅ Funds, investors, and bank accounts management screens live
  • ✅ Operations dashboard wired to RunEndOfDay use case
  • ⚠️ Organization tooling, advanced workflows, and holistic testing pending

Implementation Strategy​

Phase 1: Foundation & Infrastructure (Week 1)​

1.1 TRPC Client Setup (Modern v11 Pattern)​

// New TRPC v11 pattern with TanStack Query integration
const trpc = useTRPC();
const fundQuery = useQuery(trpc.tenant.fund.getAll.queryOptions());
const createMutation = useMutation(trpc.tenant.fund.create.mutationOptions());

Tasks:

  • setup-trpc-client: Configure TRPC v11 client with new TanStack Query integration
  • setup-auth-integration: Integrate with existing auth middleware (tenantProcedure, systemProcedure)
  • create-role-guards: Build role-based UI components using existing ROLE_HIERARCHY
  • setup-shadcn-ui: Install and configure ShadCN UI with financial components

1.2 Layout & Navigation (Role-Based)​

// Role-based navigation using existing role system
const navigationItems = [
  { label: "Funds", route: "/funds", roles: [ROLES.MEMBER] },
  {
    label: "Operations",
    route: "/operations",
    roles: [ROLES.MANAGER],
  },
];

Tasks:

  • create-layout-components: Header, Sidebar, MainLayout with role-based navigation
  • setup-file-based-routing: Configure Tanstack Router file-based routing structure

Phase 2: Core Domain Implementation (Week 2)​

2.1 Fund Management (Most Critical)​

Backend Integration: Uses existing FundService and SetupFundUseCase
TRPC Routes: tenantProcedure with existing fund schemas

Tasks:

  • implement-fund-routes: Create TRPC fund routes using existing FundService
  • create-fund-management-ui: Fund list, detail, creation using SetupFundUseCase
  • implement-data-loaders: Tanstack Router loaders for fund data using TRPC queryOptions

2.2 Investor Management​

Backend Integration: Uses existing InvestorService and PurchaseUnitsUseCase
TRPC Routes: tenantProcedure with existing investor schemas

Tasks:

  • implement-investor-routes: Create TRPC investor routes using existing InvestorService
  • create-investor-management-ui: Investor list and maintenance UI (unit purchase workflow still pending)
  • add-investor-transaction-flows: Implement unit purchase and redemption workflow leveraging PurchaseUnitsUseCase

Phase 3: Financial Operations (Week 3)​

3.1 Bank Account Management​

Backend Integration: Uses existing BankAccountService
TRPC Routes: tenantProcedure with existing bank account schemas

Tasks:

  • implement-bank-account-routes: Create TRPC bank account routes
  • create-bank-account-ui: Bank account list, detail, transaction history

3.2 Operations Dashboard​

Backend Integration: Uses existing RunEndOfDayUseCase
TRPC Routes: tenantProcedure for operations

Tasks:

  • implement-operations-routes: Create TRPC operations routes for EOD processing
  • create-operations-dashboard: EOD status, manual triggers, progress monitoring

Phase 4: Organization & System Management (Week 4)​

4.1 Organization Management​

Backend Integration: Uses existing OrganizationService
TRPC Routes: systemProcedure and tenantProcedure

Tasks:

  • implement-organization-routes: Create TRPC organization routes
  • create-organization-ui: Organization management, tenant switching

4.2 Advanced Features​

Tasks:

  • create-financial-components: MoneyDisplay, PercentageDisplay shipped (financial charts pending)
  • setup-form-validation: React Hook Form integration with TRPC schemas
  • implement-search-filtering: Data tables with TRPC pagination

Phase 5: Testing & Quality (Week 5)​

5.1 Testing Infrastructure​

Tasks:

  • create-testing-infrastructure: Set up testing for TRPC routes and Tanstack Router
  • write-integration-tests: Test TRPC routes with mock services from your factory
  • write-component-tests: Test UI components with role-based access

5.2 Error Handling & UX​

Tasks:

  • setup-error-handling: Comprehensive error handling for TRPC and auth failures
  • implement-loading-states: Suspense boundaries and loading states
  • add-accessibility: WCAG compliance for financial applications

Phase 6: Reporting & Optimization (Week 6)​

6.1 Reporting & Analytics​

Tasks:

  • create-reporting-views: Fund performance, investor activity reports
  • setup-real-time-updates: TRPC subscriptions or polling for live data

6.2 Performance & Deployment​

Tasks:

  • optimize-performance: Tanstack Query caching, Tanstack Router code splitting
  • setup-deployment: Cloudflare Pages deployment pipeline

Technical Implementation Details​

TRPC v11 Integration Pattern​

// Modern TRPC v11 pattern
export function FundList() {
  const trpc = useTRPC();
  const queryClient = useQueryClient();

  // Query with new v11 pattern
  const fundsQuery = useQuery(trpc.tenant.fund.getAll.queryOptions({
    organizationId: user.organizationId,
  }));

  // Mutation with new v11 pattern
  const createMutation = useMutation(trpc.tenant.fund.create.mutationOptions());

  // Query key for cache manipulation
  const fundQueryKey = trpc.tenant.fund.getAll.queryKey();
  const invalidateFunds = () => {
    queryClient.invalidateQueries({ queryKey: fundQueryKey });
  };

  return (
    <div>
      {fundsQuery.data?.map(fund => (
        <FundCard key={fund.id} fund={fund} />
      ))}
    </div>
  );
}

Tanstack Router Data Loading Pattern​

// Route-level data loading
export const Route = createFileRoute("/funds")({
  component: FundListPage,
  loader: ({ context }) => {
    const trpc = context.trpc;
    return trpc.tenant.fund.getAll.queryOptions({
      organizationId: context.user.organizationId,
    });
  },
});

// Component-level suspense queries
export function FundListPage() {
  const trpc = useTRPC();
  const fundQuery = useSuspenseQuery(trpc.tenant.fund.getAll.queryOptions());

  return (
    <div>
      {fundQuery.data.map(fund => (
        <FundCard key={fund.id} fund={fund} />
      ))}
    </div>
  );
}

Role-Based Component Pattern​

// Leverage existing role system
function RoleGuard({
  requiredRole,
  children,
  fallback = null
}: {
  requiredRole: Role;
  children: React.ReactNode;
  fallback?: React.ReactNode;
}) {
  const { user } = useAuth();

  if (!user || !hasPermission(user.role, requiredRole)) {
    return <>{fallback}</>;
  }

  return <>{children}</>;
}

// Usage
<RoleGuard requiredRole={ROLES.MANAGER}>
  <FundManagementPanel />
</RoleGuard>

File Structure​

src/
├── components/
│   ├── ui/                    # ShadCN components
│   ├── financial/             # Financial-specific components
│   │   ├── MoneyDisplay.tsx
│   │   ├── PercentageDisplay.tsx
│   │   └── FundCard.tsx
│   ├── layout/                # Layout components
│   │   ├── Header.tsx
│   │   ├── Sidebar.tsx
│   │   └── MainLayout.tsx
│   └── role-guard.tsx         # Role-based access control
├── routes/
│   ├── funds/                 # Fund management routes
│   │   ├── index.tsx
│   │   ├── $fundId.tsx
│   │   └── create.tsx
│   ├── investors/             # Investor management routes
│   ├── bank-accounts/         # Bank account routes
│   ├── operations/            # Operations dashboard routes
│   └── organizations/         # Organization management routes
├── lib/
│   ├── trpc.ts               # TRPC client configuration
│   ├── auth.ts               # Auth utilities
│   └── roles.ts              # Role checking utilities
├── hooks/
│   ├── use-auth.ts           # Auth context hook
│   ├── use-role.ts           # Role checking hook
│   └── use-trpc.ts           # TRPC client hook
└── __tests__/                # Frontend tests
    ├── components/
    ├── routes/
    └── trpc/

Testing Strategy​

TRPC Route Testing (Server-Side Callers)​

// Test TRPC routes using server-side callers with custom context
import { setupTest, createTestCaller, buildTestUser } from "../helpers";

describe("Fund Routes", () => {
  let services: TestServices;
  let caller: ReturnType<typeof appRouter.createCaller>;

  beforeAll(async () => {
    const setup = await setupTest();
    services = setup.services;

    // Create caller with custom user context
    caller = createTestCaller({
      services,
      user: buildTestUser({
        role: ROLES.MANAGER,
        organizationId: "org-1",
      }),
    });
  });

  it("should get funds for organization", async () => {
    const result = await caller.tenant.fund.getAll({ organizationId: "org-1" });
    expect(result).toHaveLength(0);
  });

  it("should create fund with proper validation", async () => {
    const fundData = {
      name: "Test Fund",
      code: "TEST001",
      organizationId: "org-1",
      startDate: new Date("2024-01-01"),
    };

    const result = await caller.tenant.fund.create(fundData);
    expect(result.name).toBe(fundData.name);
    expect(result.code).toBe(fundData.code);
  });

  it("should enforce role-based access", async () => {
    // Test with insufficient permissions
    const unauthorizedCaller = createTestCaller({
      services,
      user: buildTestUser({ role: ROLES.USER }),
    });

    await expect(
      unauthorizedCaller.fund.create({
        name: "Test",
        code: "TEST",
        organizationId: "org-1",
      }),
    ).rejects.toThrow("Role not permitted");
  });
});

Component Testing with Role Guards​

// Test role-based access
describe('FundManagementPanel', () => {
  it('shows content for authorized users', () => {
    renderWithAuth({ role: ROLES.MANAGER })(
      <RoleGuard requiredRole={ROLES.MEMBER}>
        <FundManagementPanel />
      </RoleGuard>
    );

    expect(screen.getByText('Fund Management')).toBeInTheDocument();
  });
});

Cloudflare Workers Testing Integration​

// Leverage existing Cloudflare Vitest setup with D1 database
import { env } from "cloudflare:test";
import { setupTest, createTestCaller } from "../helpers";

describe("TRPC Routes with Cloudflare Workers", () => {
  let services: TestServices;

  beforeAll(async () => {
    // Use existing setupTest which handles D1 migrations automatically
    const setup = await setupTest({ env });
    services = setup.services;
  });

  it("should work with Cloudflare D1 database", async () => {
    const caller = createTestCaller({ services });

    // Test with actual D1 database
    const result = await caller.tenant.fund.getAll({ organizationId: "org-1" });
    expect(result).toBeDefined();
  });
});

Success Metrics & Quality Gates​

Phase Completion Criteria​

  1. Phase 1: TRPC client working, basic layout complete
  2. Phase 2: Fund and investor management functional
  3. Phase 3: Bank accounts and operations working
  4. Phase 4: Organization management complete
  5. Phase 5: All tests passing, error handling complete
  6. Phase 6: Performance optimized, deployed

Quality Gates​

  • ⚠️ All tests passing (unit, integration, component) — targeted Vitest coverage still pending
  • ✅ TypeScript strict mode compliance
  • ✅ Role-based access control working
  • ✅ TRPC integration with existing auth middleware
  • ✅ Tanstack Router file-based routing working
  • ⚠️ Accessibility standards met — formal audit outstanding
  • ⚠️ Performance benchmarks met — optimization work scheduled for Phase 6

Development Workflow​

Weekly Sprint Structure​

  • Monday: Planning and setup
  • Tuesday-Thursday: Implementation and testing
  • Friday: Integration testing and documentation
  • Weekend: Review and prepare next sprint

KISS & YAGNI Application​

  • Build only what's needed for current phase
  • Leverage existing backend infrastructure
  • Use proven patterns from research
  • Avoid over-engineering
  • Refactor when patterns emerge

Detailed TODO List​

Phase 1: Foundation & Infrastructure​

  • research-complete: Research latest Tanstack Router and TRPC v11 patterns ✅
  • setup-trpc-client: Set up TRPC v11 client with new TanStack Query integration using queryOptions/mutationOptions ✅
  • setup-auth-integration: Integrate TRPC client with existing auth system and role-based middleware ✅
  • create-role-guards: Create role-based UI components using existing role hierarchy ✅
  • setup-shadcn-ui: Set up ShadCN UI component library with financial-specific components ✅
  • create-layout-components: Create main layout components (Header, Sidebar, MainLayout) with role-based navigation ✅
  • setup-file-based-routing: Set up Tanstack Router file-based routing structure following domain patterns ✅

Phase 2: Core Domain Implementation​

  • implement-fund-routes: Implement TRPC fund routes using tenantProcedure and existing FundService ✅
  • create-fund-management-ui: Create fund management UI components with CRUD operations ✅
  • implement-data-loaders: Implement Tanstack Router data loaders for page-level data using TRPC queryOptions ✅
  • implement-investor-routes: Implement TRPC investor routes using tenantProcedure and existing InvestorService ✅
  • create-investor-management-ui: Create investor management UI for registration, editing, and detail views ✅
  • add-investor-transaction-flows: Implement unit purchase and redemption workflow using PurchaseUnitsUseCase ✅

Phase 3: Financial Operations​

  • implement-bank-account-routes: Implement TRPC bank account routes using tenantProcedure and existing BankAccountService ✅
  • create-bank-account-ui: Create bank account management UI with transaction history ✅
  • implement-operations-routes: Implement TRPC operations routes for EOD processing using RunEndOfDayUseCase ✅
  • create-operations-dashboard: Create operations dashboard with EOD status and manual triggers ✅

Phase 4: Organization & System Management​

  • implement-organization-routes: Implement TRPC organization routes using systemProcedure and tenantProcedure ✅
  • create-organization-ui: Create organization management UI with organization info display and system admin management ✅
  • create-financial-components: Create financial-specific UI components (MoneyDisplay, PercentageDisplay shipped; charts pending) ✅
  • setup-form-validation: Set up form validation using existing TRPC schemas with React Hook Form ✅
  • implement-search-filtering: Implement search and filtering for data tables using TRPC pagination (organization management has search) ✅

Phase 5: Testing & Quality​

  • create-testing-infrastructure: Set up testing infrastructure for TRPC routes and Tanstack Router components
  • write-integration-tests: Write integration tests for TRPC routes using server-side callers with custom context
  • write-component-tests: Write component tests for UI components with role-based access
  • setup-error-handling: Set up comprehensive error handling for TRPC and auth failures
  • implement-loading-states: Implement loading states and Suspense boundaries for Tanstack Router
  • add-accessibility: Add accessibility features following WCAG guidelines

Phase 6: Reporting & Optimization​

  • create-reporting-views: Create basic reporting views for fund performance and investor activity
  • setup-real-time-updates: Set up real-time updates using TRPC v11 subscriptions or polling
  • optimize-performance: Optimize performance with Tanstack Query caching and Tanstack Router code splitting
  • setup-deployment: Set up deployment pipeline for frontend with Cloudflare Pages

Key Principles​

KISS (Keep It Simple, Stupid)​

  • Leverage existing backend infrastructure
  • Use proven patterns from research
  • Build incrementally, one feature at a time
  • Avoid over-engineering

YAGNI (You Aren't Gonna Need It)​

  • Build only what's needed for current phase
  • Avoid premature optimization
  • Focus on essential business operations
  • Refactor when patterns emerge

Domain-Driven Design​

  • Follow existing domain boundaries
  • Use existing service layer
  • Maintain separation of concerns
  • Leverage existing use cases

Next Steps​

  1. Investor Transactions: Implement purchase/redemption UI dialogs and supporting workflow states (backend routes already exist).
  2. Create/Edit Organization Dialogs: Add dialog forms for system admins to create and edit organizations (optional polish).
  3. Quality Pass: Stand up focused integration/component tests, tighten error handling, and add loading/accessibility coverage.
  4. Plan Advanced Features: Scope financial charting, reporting views, and performance work targeted for Phase 6.

Document Owner: Development Team
Last Updated: October 2025
Next Review: After Phase 1 completion