MSFLib React Monorepo – Module Outline¶

This repository is a monorepo for modular, standalone React libraries that pair with the msflib FastAPI backend. The shared foundation lives in the core package, and feature capabilities are split into independently installable modules. Each module is built on TanStack Query v5, follows the same provider + hook pattern, and integrates with @msflib/core's multi-tenant/workspace scoping — so once you've used one module, the rest feel the same.

Quick Start¶

Get a working login screen in under 5 minutes. This uses @msflib/react-auth as the example, but every module follows the exact same three steps: configure once, wrap your app in a provider, use a hook.

1. Install¶

pnpm add @msflib/core @msflib/react-auth @tanstack/react-query

2. Configure (once, at app startup)¶

// e.g. in your app's root layout or entry file
import { configureApplication } from '@msflib/core';

configureApplication({
  baseURL: 'https://devbe.ifusion.kodehauz.dev',
  accessTokenKey: 'access_token',
});

3. Wrap your app¶

import type { ReactNode } from 'react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { AuthProvider } from '@msflib/react-auth';

const queryClient = new QueryClient();

export default function App({ children }: { children: ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <AuthProvider>{children}</AuthProvider>
    </QueryClientProvider>
  );
}

4. Use the hook¶

import { useAuth } from '@msflib/react-auth';

function LoginForm() {
  const { login, status, me } = useAuth();

  if (status === 'authenticated') {
    return <p>Welcome back, {me?.username}!</p>;
  }

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        const form = new FormData(e.currentTarget);
        login({
          email: form.get('email') as string,
          password: form.get('password') as string,
        });
      }}
    >
      <input name="email" type="email" placeholder="Email" required />
      <input name="password" type="password" placeholder="Password" required />
      <button type="submit">Log in</button>
    </form>
  );
}

That's it — status and me update automatically once login succeeds. Every other module (react-profile, react-workspace, react-documents, ...) follows this same pattern: pnpm add, one *Provider wrapping your app, one use* hook. See the package index below for each module's own page with its full API.

Core package¶

@msflib/core — Framework-agnostic foundation used by every other module. Provides global application configuration (configureApplication), a safe browser storage wrapper, and the multi-tenant/workspace-scoping runtime (resolveWorkspaceScopedEndpoint, isWorkspaceScopedEndpoint, configuredApiClient) that all domain modules build on.
@msflib/react-shared — Common React hooks and helpers shared across react-auth, react-notification, react-profile, and the other domain modules.
@msflib/react-ux — Small, UI-agnostic React utilities for common product interactions (independent of any specific component library).
@msflib/react-components — Shared UI component library: FormBuilder, data tables, a chat UI kit (with Markdown rendering and an "agent thinking" status pattern), drag-and-drop, tree views, Google auth buttons, resizable panes, skeletons, OTP input, and custom SVG icons.
@msflib/testing (dev dependency) — Shared Vitest testing utilities: createHoisedMocks() and friends eliminate repeated mock boilerplate across module test suites.

Module summaries¶

@msflib/react-auth — Authentication module: login/token issuance, logout, password reset/recovery, OTP and SSO (redirect/retrieve) flows, and optional workspace-scoped sessions.
@msflib/react-profile — User-profile module: profile CRUD, avatar upload, and the same optional workspace-scoped sessions as react-auth.
@msflib/react-users — User management module, integrated with @msflib/core + @msflib/react-shared.
@msflib/react-workspace — Workspace lifecycle module: list/get/create/update/delete, with configurable per-endpoint workspace scoping.
@msflib/react-categories — Categories module, integrated with @msflib/core + @msflib/react-shared.
@msflib/react-notification — Headless notification state (in-app notifications, admin broadcasts) backed by the configured API.
@msflib/react-support — Multi-tenant support module, following the same pattern as the other feature modules.
@msflib/react-certificate — Multi-tenant certificate module, following the same pattern as the other feature modules.
@msflib/react-ai — Multi-tenant LLM + Agent module. Wraps the backend's /llm/* and /agent/* endpoints, including streaming agent responses via askStream/readAskStream.
@msflib/react-documents — Documents module for the LMS backend.
@msflib/react-drivelink — Drivelink (virtual filesystem / drive-style) module.
@msflib/react-courses — Courses module, wraps the LMS backend's courses API.
@msflib/react-curriculum — Curriculum module for the LMS backend.
@msflib/react-lesson — Lesson module for the LMS backend.
@msflib/react-students — React Query helpers for the LMS students API.
@msflib/react-trainers — React Query helpers for the LMS trainers API.
@msflib/react-tasks — Tasks module for the LMS backend.
@msflib/react-lottery — Lottery module built on TanStack Query.

Overall architecture¶

@msflib/core provides the shared primitives (config, storage, multi-tenant/workspace scoping) that every other module is built on.
Domain modules extend the platform with business logic while reusing the same provider + hook + TanStack Query pattern for data access.
@msflib/react-components is kept independent of any domain module, so it can be used purely for its UI building blocks (forms, tables, chat UI) regardless of which backend modules a project pulls in.
Each module is published separately to GitHub Packages, so a consuming app only installs the modules it actually needs.