frontend-patterns

Admin Frontend Patterns

Mock/Live API Architecture

Each API domain has 3 files:

1. Live API (src/lib/{domain}ApiLive.ts)

export async function fetchUsers(
  accessToken: string,
  query: AdminUsersQuery
): Promise<AdminUsersResponse> {
  return requestJSON<AdminUsersResponse>(
    `${BACKEND_URL}/admin/users?${buildQuery(query)}`,
    { headers: { Authorization: `Bearer ${accessToken}` } }
  );
}

2. Mock API (src/lib/{domain}ApiMock.ts)

export function mockFetchUsers(query: AdminUsersQuery): AdminUsersResponse {
  // Deterministic mock data from src/data/mockData.ts
  return { data: mockUsers.slice(offset, offset + limit), total: mockUsers.length };
}

3. Client Wrapper (src/lib/{domain}ApiClient.ts)

export function createAdminUsersApiClient(accessToken?: string) {
  const mode = resolveMode('VITE_ADMIN_USERS_MODE', 'adminUsersMode');

  return {
    fetchUsers: withReadFallback(
      (q) => fetchUsersLive(accessToken!, q),
      (q) => mockFetchUsers(q),
      mode
    ),
  };
}

Mode resolution order:

1. VITE_{DOMAIN}_MODE env var
2. localStorage['{domain}Mode']
3. Auth/access mode fallback
4. Default: 'live'

Fallback strategy:

• withReadFallback: try live → fall back to mock on error
• withWriteFallback: try live → throw on error (no mock writes)

Page Component Pattern

// src/pages/MyPage.tsx
export function MyPage({ accessToken }: { accessToken?: string }) {
  const [data, setData] = useState<MyData | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const [filters, setFilters] = useState(() => {
    // Restore from localStorage if needed
  });

  useEffect(() => {
    const controller = new AbortController();
    const client = createMyApiClient(accessToken);
    client.fetchData(filters)
      .then(setData)
      .catch(e => setError(e.message))
      .finally(() => setLoading(false));
    return () => controller.abort();
  }, [accessToken, filters]);

  return (/* JSX */);
}

// Optional: TopBar actions for this page
export function MyPageTopBarActions({ ... }) {
  return (/* filter controls, export buttons */);
}