rakib-cloud/car-allocation

1. Overall shape

- This is a Next.js 16 App Router admin panel for car allocation.

- The app is split into two top-level route groups: authenticated admin pages under src/app/(root) and a public sign-in flow under src/app/(auth).

- A separate maintenance route and a middleware.js boundary indicate some requests can be short-circuited before reaching the normal shell.

2. Route and layout boundaries

- src/app/layout.jsx is the global root layout.

- src/app/(root)/layout.jsx wraps the authenticated area and likely provides the admin shell structure.

- src/components/ui/layouts/admin-layout.jsx, header.jsx, sidebar.jsx, and mobile-footer-nav.jsx form the main navigation shell for desktop/mobile.

- src/app/(auth)/sign-in/page.jsx intentionally sits outside the admin shell, so login has a separate UI and no sidebar/header.

3. Authentication model

- Authentication is JWT-based with httpOnly cookies, which means the browser does not manage tokens directly in client state.

- src/lib/auth/manual-auth.js and the actions under src/lib/actions/auth-actions/ imply a server-centered auth flow.

- sign-in-action.js handles login, token-refresh-action.js handles session renewal, and authorized-request-action.js likely wraps authenticated backend calls.

- src/app/(root)/AuthContext.jsx suggests the authenticated UI still keeps a lightweight client-side auth/session context for downstream components.

4. Request and API layer

- The repo avoids axios and uses a central native fetch wrapper in src/lib/httpClient.js.

- src/constant/api-url.js provides API endpoint definitions, while src/lib/api-envelope.js normalizes response shape across backend calls.

- Error handling is centralized in src/lib/helpers/handle-api-errors.js, so API failures are standardized before reaching UI components.

- src/lib/actions/allocation-actions.js indicates feature-specific server actions for allocation-related backend operations.

5. Server Actions as the primary mutation boundary

- Business mutations appear to happen through Next.js Server Actions rather than direct client API calls.

- This places sensitive work like token handling, refresh logic, and authenticated requests on the server side.

- The architecture therefore separates:

- client UI components for interaction,

- server actions for secure data access and mutations,

- backend API as the source of truth.

6. UI composition and shared components

- src/components/ui/ contains reusable shell primitives and navigation pieces.

- src/components/common/loader.jsx and src/app/loading.jsx provide loading states at different levels of the app.

- src/components/wrappers/page-wrapper.jsx is likely the main page-level gate for access checks and layout consistency.

- src/components/ui/user-role-permission.jsx suggests role-aware rendering is embedded into the UI layer, not just route protection.

7. Access control and route protection

- middleware.js is the first-line boundary for routing/auth decisions and likely enforces redirects or maintenance behavior.

- src/components/wrappers/page-wrapper.jsx and user-role-permission.jsx suggest an additional RBAC layer after navigation, controlling what authenticated users can see.

- This creates a two-step model: request-level gating in middleware and UI-level authorization inside the admin shell.

8. Maintenance mode path

- src/app/maintenance/page.jsx and src/constants/maintenanceMode.js show a dedicated maintenance state.

- The existence of this route plus middleware support implies the app can be globally diverted away from the main admin experience when the environment flag is enabled.

- This is an operational boundary separate from authentication.

9. Theming and providers

- src/providers/antd-provider.jsx and src/providers/theme-provider.jsx establish cross-app UI infrastructure.

- The stack combines Ant Design 6 with Tailwind CSS 4, so component styling is split between design-system widgets and utility classes.

- The README notes the theme is stored in localStorage under car-allocation-theme, so theme preference is client persisted.

10. Data shaping and helper layer

- src/lib/utils/normalize-detail-response.js, src/lib/utils/utils.js, and src/lib/helpers/toaster-helper.js are shared utilities for response normalization, generic helpers, and user notifications.

- src/hooks/useDetailFetch.js indicates at least one reusable data-fetching hook for detail views.

- These helpers reduce duplication around fetching, formatting, and error display.

11. Branding and configuration

- src/constant/branding.js and the theme note in the README indicate the UI is branded and color-coded centrally.

- env.example shows key runtime flags: NEXT_PUBLIC_API_BASE_URL, MAINTENANCE_MODE, and AUTH_COOKIE_SECURE.

- That means the deployment environment directly influences routing, auth cookie behavior, and backend target selection.

12. How data flows through the app

- User hits middleware first.

- If not authenticated, they are routed to /sign-in.

- Sign-in triggers a server action that calls the backend API through the centralized fetch layer, then stores session state in httpOnly cookies.

- Authenticated pages render inside the root layout/admin shell, use shared providers, and fetch/mutate data via server actions and the HTTP wrapper.

- Responses are normalized before reaching components, and role-based wrappers decide what portions of the UI are exposed.