Web Folder Structure

Web Folder Structure

The merq-web codebase follows a standard feature-oriented structure for React applications, built with Vite and TypeScript. It is designed to be modular and easy to navigate.

High-Level Structure

• Directorysrc/ - The main application source code.

  • Directorypages/ - Top-level route components, representing a full page.

    • …
  • Directorycomponents/ - Reusable UI components shared across the application.

    • Directoryui/ - Core, unstyled components from shadcn/ui.

      • …
    • Directorycommon/ - Application-specific components (e.g., CommonTable, DialogTable).

      • …
  • Directorylib/ - Core logic, API communication, and utilities.

    • api.ts - The configured Axios instance for all API calls.
    • Directoryquery/ - TanStack Query hooks, organized by entity.

      • …
    • Directoryconstants/ - Application-wide constants (routes, permissions).

      • …
  • Directoryhooks/ - Shared custom React hooks.

    • …
  • Directorycolumns/ - TanStack Table column definitions, organized by entity.

    • …
• Directorypublic/ - Static assets that are copied directly to the build output.

  • …
• index.html - The main HTML entry point for the SPA.
• vite.config.ts - The Vite build configuration.
• package.json - Project metadata and dependencies.

The src/ Directory in Detail

The src/ directory contains all the React application code.

pages/

• Purpose: Contains the main component for each route in the application.
• Responsibilities:
  • Lays out the main structure of a page (e.g., header, content area).
  • Fetches data using the appropriate TanStack Query hooks from lib/query/.
  • Manages page-level state and filter states.
  • Renders shared components like CommonTable and passes data to them.
• Example: pages/UsersPage.tsx would be the component for the /users route, responsible for fetching and displaying the list of users.

components/

• Purpose: Contains reusable React components.
• Subdirectories:
  • ui/: This is where the base shadcn/ui components are located (e.g., Button.tsx, Input.tsx, Dialog.tsx). These are generally not modified directly but are imported and used throughout the app.
  • common/: Contains higher-level components built from the ui/ blocks. For example, CommonTable.tsx is a reusable wrapper around the TanStack Table library, and PageHeader.tsx is a consistent header for all pages.

lib/

• Purpose: The central hub for application logic and communication.
• Subdirectories:
  • api.ts: A single, pre-configured Axios instance. It sets the baseURL for the backend and includes an interceptor to automatically attach the JWT authentication token to every outgoing request. All API calls must use this instance.
  • query/: Contains all TanStack Query hooks, organized by data entity. Each file (e.g., users.ts) exports hooks for fetching, creating, updating, and deleting that entity (e.g., useUsersQuery, useCreateUserMutation). This is the only place where data fetching logic should reside.
  • constants/: Holds application-wide constants, such as route paths (routes.ts) and permission strings (route-permissions.ts), ensuring consistency.

hooks/

• Purpose: Contains shared, reusable custom React hooks that are not related to data fetching.
• Example: usePaginationSearchParam.tsx is a hook that synchronizes table pagination state with URL query parameters, allowing for shareable links to specific pages of data.

columns/

• Purpose: Defines the column structure for TanStack Tables.
• Responsibilities:
  • Each file (e.g., usersColumns.tsx) exports a ColumnDef[] array for a specific data entity.
  • Defines which data fields to show, the header labels, and any custom cell rendering (e.g., rendering a status badge or an actions menu).
• Benefit: By separating column definitions, tables are kept clean and the column logic can be reused in different parts of the app (e.g., on a main page and in a selection modal).