122 lines
8.5 KiB
Markdown
122 lines
8.5 KiB
Markdown
# Frontend Source File Structure
|
|
|
|
This document provides a comprehensive overview of the QAssure Frontend codebase structure, architectural layers, directory mapping, and design patterns.
|
|
|
|
---
|
|
|
|
## 1. Architectural Overview
|
|
|
|
The QAssure frontend is built as a Single Page Application (SPA) using **React (v19), TypeScript, Vite, Tailwind CSS, and Redux Toolkit**. The architecture follows a modular, feature-oriented structure with strict separation between UI rendering and API communication:
|
|
|
|
```mermaid
|
|
graph TD
|
|
User[User Interaction] --> View[React Page/Component: JSX + Tailwind CSS]
|
|
View --> Hooks[Custom Hooks: useAppSelector, useTenantTheme]
|
|
Hooks --> ReduxStore[Redux Toolkit Store: Slices for Auth, Theme, Notifications]
|
|
View --> Form[Form Layer: React Hook Form + Zod Schema Validation]
|
|
Form --> Service[Service Layer: API call wrappers via Axios]
|
|
Service --> AxiosClient[Axios Client: Interceptors for JWT & Refresh token handling]
|
|
AxiosClient --> BackendAPI[(QAssure Backend API v1)]
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Directory Layout & Key Components
|
|
|
|
Below is the directory map of the frontend project with the purpose of each directory:
|
|
|
|
```
|
|
qassure-frontend/
|
|
├── .env # Configuration variables (VITE_API_BASE_URL)
|
|
├── .env.example # Template configuration variables
|
|
├── index.html # Root HTML entry point
|
|
├── package.json # Frontend dependencies and run scripts
|
|
├── tsconfig.json # TypeScript compiler base settings
|
|
├── vite.config.ts # Vite build and plugin configurations (Tailwind CSS, React, path aliases)
|
|
├── tailwind.config.js / css # Tailwind styling presets and directives
|
|
│
|
|
├── public/ # Static public assets (icons, images, manifest)
|
|
│
|
|
├── src/ # Main source code folder
|
|
│ ├── App.tsx # Main React entry component wrapping Providers (Redux, Router)
|
|
│ ├── main.tsx # ReactDOM bootstrapper mounting App to DOM
|
|
│ ├── index.css # Global CSS styles and Tailwind base configurations
|
|
│ │
|
|
│ ├── assets/ # Local media assets (logos, svg icons, branding graphics)
|
|
│ ├── auth/ # Session tracking helpers, contexts, or legacy providers
|
|
│ │
|
|
│ ├── components/ # Reusable UI components
|
|
│ │ ├── layout/ # Shell components: Sidebar, Header, Page Layout definitions
|
|
│ │ ├── shared/ # Global standard components: Button, Modal, Table, StatusBadge
|
|
│ │ ├── superadmin/ # Components scoped specifically for Super Admin dashboard views
|
|
│ │ ├── tenant/ # Components scoped specifically for Tenant users dashboard views
|
|
│ │ └── ui/ # Primitive custom form inputs, sliders, and design elements
|
|
│ │
|
|
│ ├── constants/ # Immutable global configuration values, states, and text mappings
|
|
│ ├── features/ # State slices or business-feature specific logic
|
|
│ ├── hooks/ # Custom global React hooks (Redux shortcuts, theme listeners)
|
|
│ ├── lib/ # Configuration and initialization files for libraries
|
|
│ │
|
|
│ ├── pages/ # Routed page views (containers containing page state)
|
|
│ │ ├── superadmin/ # Views accessible to Super Admins (Storage Configs, Module Masters)
|
|
│ │ ├── tenant/ # Views accessible to Tenant Admins/Users (Settings, Documents, Tasks)
|
|
│ │ ├── Login.tsx # Super Admin login landing view
|
|
│ │ ├── TenantLogin.tsx # Tenant-specific portal login view
|
|
│ │ ├── ProtectedRoute.tsx # Higher-Order Component protecting Super Admin routes
|
|
│ │ └── NotFound.tsx # 404 fallback page
|
|
│ │
|
|
│ ├── routes/ # Routing configuration definitions
|
|
│ │ ├── index.tsx # Core Router provider mounting routes and lazy loading modules
|
|
│ │ ├── public-routes.tsx # Paths accessible without authentication
|
|
│ │ ├── super-admin-routes.tsx# Navigation routes for Super Admins
|
|
│ │ └── tenant-admin-routes.tsx# Navigation routes for Tenant Admins
|
|
│ │
|
|
│ ├── services/ # API client configurations and API request services
|
|
│ │ ├── api-client.ts # Central Axios client with token injection & automated token-refresh loop
|
|
│ │ ├── storage-bucket-service.ts # Storage bucket CRUD and tenant assignment services
|
|
│ │ └── ...and more services # Services mapping to backend endpoints
|
|
│ │
|
|
│ ├── store/ # Redux Toolkit global store configuration
|
|
│ │ ├── store.ts # Redux store instantiation with persisting logic (Redux Persist)
|
|
│ │ ├── authSlice.ts # State slice for user session, access/refresh tokens, and roles
|
|
│ │ ├── themeSlice.ts # State slice for dark/light modes and dynamic tenant branding themes
|
|
│ │ └── notificationSlice.ts # State slice for central notifications and unread badges
|
|
│ │
|
|
│ ├── styles/ # Modular style components, custom css overrides
|
|
│ ├── types/ # Unified TypeScript interface declarations matching backend models
|
|
│ └── utils/ # Global utility methods: formatters, token decoders, and validation rules
|
|
│
|
|
└── docs/ # Developer manuals and deployment context documentation
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Key Core Modules & Configurations
|
|
|
|
### 3.1 Routing & Security Boundary
|
|
* **`src/routes/`**: Handles application URL navigation. Uses React Router DOM's lazy-loading component approach to split bundles dynamically.
|
|
* **`ProtectedRoute.tsx` & `TenantProtectedRoute.tsx`**: Guards routes. Intercepts navigation attempts, reads the user session state from the Redux store, redirects unauthorized requests to appropriate login portals, and manages role validation.
|
|
|
|
### 3.2 Global State Management
|
|
* **`src/store/`**: Runs Redux Toolkit.
|
|
* `authSlice.ts` maintains user credentials, authorization status, and roles.
|
|
* `themeSlice.ts` manages style definitions. It supports tenant-specific dynamic theming, parsing primary and secondary hex codes retrieved on tenant login, and injecting them into HTML styling variables.
|
|
* `store.ts` wraps slices inside `redux-persist` so that user auth states are saved in localStorage and survived through browser page reloads.
|
|
|
|
### 3.3 Network Communication Layer
|
|
* **`src/services/api-client.ts`**: The central network connector. It provides:
|
|
1. **Authorization Interceptor**: Dynamically grabs the active JWT token from the Redux store on every outgoing request and injects it as an `Authorization: Bearer <token>` header.
|
|
2. **Automated Refresh Token Interceptor**: Monitors response streams. If a request fails with an HTTP `401 Unauthorized` status (due to token expiration), the client freezes the request queue, invokes the `/auth/refresh` API to fetch new tokens, dispatches them to the Redux store, and automatically retries the frozen requests.
|
|
|
|
### 3.4 Form & Input Validation
|
|
* **`src/components/ui/` & `src/validation/`**: Inputs are handled using **React Hook Form**. Validations are defined using **Zod schema validations** matching backend constraints. Resolvers bind Zod constraints directly to form schemas, displaying real-time frontend field errors to the user before submitting.
|
|
|
|
---
|
|
|
|
## 4. Coding & UX Standards
|
|
|
|
1. **Component Architecture**: Always split large view files into reusable sub-components in the same directory, or place them under `src/components/shared/` if they are utilized by multiple domains.
|
|
2. **Type Safety**: Define TypeScript types inside `src/types/` for all network response structures and component parameters. Avoid using `any`.
|
|
3. **Strict Styling Isolation**: Do not use ad-hoc style sheets or inline CSS for spacing. Apply standard Tailwind classes. Dynamic properties like branding themes must be styled using Tailwind's CSS variable mapping.
|
|
4. **No Direct Axios Calls**: Never trigger direct `axios.get` or `axios.post` in page views. All API communication must be funneled through dedicated service files located in `src/services/` to keep page logic decoupled.
|