# haroonalshaji/nexus_built architecture

> Architecture diagram of the GitHub repository haroonalshaji/nexus_built, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/haroonalshaji/nexus_built
- Repository: https://github.com/haroonalshaji/nexus_built

## Overview

This repository is a Next.js App Router application that behaves like a large admin/dashboard template. The architecture is mostly presentation-driven: pages are composed from reusable UI components, shared layouts, local data files, and a small set of app-wide context/providers. There is very little sign of a domain backend; most “data” appears to be static/demo content or locally managed UI state.

Main structural boundary

- `src/app` is the route layer and the primary architecture boundary.
- `src/components` contains shared, cross-route building blocks.
- `src/context`, `src/hooks`, and `src/utils` hold app-wide behavior and integration logic.
- `src/assets` holds styling, images, icons, and static data used by pages.
- `src/app/api` contains the only explicit server API surface: NextAuth authentication routes.

Routing and page organization

The app is divided into two major route groups:

1. `src/app/(admin)`
   - The protected/admin shell.
   - Contains the bulk of the application: dashboards, customers, property, posts, agents, charts, forms, tables, maps, widgets, messages, inbox, calendar, UI demos, and various business-like pages.
   - Many sections have subroutes for list/grid/detail/create variants, suggesting a consistent CRUD-style navigation model.

2. `src/app/(other)`
   - Public or secondary routes.
   - Includes authentication flows (`sign-in`, `sign-up`, `reset-password`, `lock-screen`), maintenance, coming-soon, and 404/error pages.
   - These are structurally separate from the admin experience, which implies different layout and access-control behavior.

There is also a dynamic route in the admin area:
- `src/app/(admin)/property/details/[id]/page.jsx`
  - This indicates property detail pages can be opened by identifier, likely driven by route params.

Layout and shell composition

The application’s visual shell is split into shared layout primitives:

- `src/app/layout.jsx`
  - Root layout for the whole app.
- `src/app/(admin)/layout.jsx`
  - Admin-specific layout boundary.
- `src/components/layout`
  - Top navigation, vertical navigation, footer, and related controls.
  - The admin UI is likely built around a persistent sidebar + top bar layout, with page content rendered inside.

The layout system is enriched by small header controls and shell utilities:
- left sidebar toggle
- maximize screen
- notifications
- profile dropdown
- theme mode toggle
- theme customizer toggle
- hover menu toggle

This suggests the app is a configurable dashboard UI with global UI state like theme, sidebar state, and screen mode.

Global providers, guards, and app-wide state

Several wrappers and contexts provide shared behavior across routes:

- `src/components/wrappers/AppProvidersWrapper.jsx`
  - Central place for React providers.
- `src/components/wrappers/AuthProtectionWrapper.jsx`
  - Guards protected areas and likely coordinates redirects based on auth status.
- `src/middleware.js`
  - Route-level protection/redirect layer, likely used to keep unauthorized users out of admin pages.
- `src/app/api/auth/[...nextauth]`
  - NextAuth route handlers.
  - `options.js` and `route.js` indicate session/auth configuration is handled through NextAuth.

App-wide contexts live in `src/context`:
- `useLayoutContext.jsx`
- `useChatContext.jsx`
- `useEmailContext.jsx`
- `useNotificationContext.jsx`

These suggest four main global state domains:
- layout state: sidebar/theme/menu behavior
- chat state: messaging UI
- email state: inbox/mail UI
- notification state: alerts/badges

The data flow here is mostly:
browser route -> page component -> shared layout/wrapper -> context-driven UI state -> component tree

Feature composition pattern

Most feature areas follow a consistent internal pattern:

- A route `page.jsx`
- A small set of feature-specific components in a `components/` folder
- Sometimes a `data.js` file with local demo data

Examples:
- dashboards
- customers
- property
- agents
- post
- inbox
- calendar
- charts
- forms
- tables
- advanced UI demos

This indicates the repository is organized around “feature slices” rather than a centralized domain model.

Notable business/domain clusters

Although it is a UI template, the naming shows several functional clusters:

- Dashboards
  - `agent`, `analytics`, `customer`
  - Composed from cards, charts, stats, funnel views, and summary panels.
- Property management
  - list/grid/detail/add flows
  - category and subcategory management UI
  - property detail and owner detail views
- Customers
  - add, grid-view, list-view, details
  - transaction history and owned property panels
- Agents
  - add, details, grid-view, list-view
- Posts/Blog-like content
  - create, details, list page
- Messaging and inbox
  - chat and email-inspired modules
- Calendar
  - separate page-level state hook and event editor UI
- Widgets
  - reusable dashboard blocks
- Forms, tables, charts, maps, UI components
  - demo/utility pages showcasing integrations

This creates a diagram with many feature subtrees fed by shared UI and shared data assets.

Shared component library

`src/components` is the reusable foundation used across features. It includes:

- layout primitives
- loading/fallback components
- generic cards and page titles
- modal helpers
- file upload and date input controls
- table/export helpers
- theme customizer
- icon wrappers
- vector maps
- form input wrappers

These shared components reduce duplication across the many route-specific pages. In architectural terms, most feature pages depend on this shared layer rather than implementing UI primitives themselves.

Hooks and local behavior

`src/hooks` and `src/utils/hooks` provide client-side behavior and state helpers, including:

- clipboard handling
- countdown timers
- fetch/data loading
- file upload
- local storage persistence
- modal toggling
- query-string handling
- range sliders
- generic toggle and viewport detection
- auth redirect logic

These hooks are used to make the mostly-static UI interactive without introducing a heavy state-management system. The interaction model appears largely local and component-scoped, with contexts handling the few shared app states.

Data and service layer

There are two kinds of data sources in the repo:

1. Static/local content
   - `src/assets/data/*`
   - route-local `data.js` files
   - These likely contain demo rows, chart datasets, menu items, and placeholder content.

2. Utility/API integrations
   - `src/utils/axios.js`
   - `src/utils/apiCalls/auth.js`
   - `src/utils/apiCalls/commonApi.js`
   - cookie helpers, date helpers, casing helpers, icon lookup helpers, promise helpers

This suggests a thin service layer:
- UI components consume either static datasets or utility-backed async calls.
- Authentication has explicit API integration through NextAuth.
- Cookie and localStorage helpers indicate user/session/theme persistence.

Styling and design system

Styling is a major part of the architecture:

- `src/assets/scss/app.scss` is the main stylesheet entry point.
- SCSS is organized into:
  - components
  - pages
  - plugins
  - structure
  - config
  - icons

This indicates a design-system-like approach where:
- component styles define reusable UI patterns
- page styles handle feature-specific visuals
- plugin styles support third-party integrations
- structure styles define the shell chrome
- config styles define theme variables and dark mode support

The presence of many plugin styles also shows the app integrates heavily with external UI libraries and visual widgets such as charts, calendars, maps, sliders, editors, toast systems, and carousels.

External integration points that matter architecturally

The repo is not a generic CRUD app; it is an integration-heavy dashboard. Important third-party surfaces implied by file names and styles include:

- Next.js App Router
- NextAuth for authentication/session handling
- charting libraries
- map widgets
- calendar widgets
- rich text/editor components
- drag/drop and file upload components
- toast/alert/modal libraries
- UI primitives for select, range slider, simplebar, swiper, and data tables

These integrations matter because they drive the feature split between:
- shared wrappers/components
- page-level feature components
- plugin-specific styling and data files

How data flows through the app

A typical route flow looks like this:

1. User enters a route under `(admin)` or `(other)`.
2. The relevant Next.js page component renders.
3. The page composes shared layout and feature components.
4. Shared wrappers/providers supply auth, theme, layout, chat/email/notification state.
5. Feature components read local `data.js` files, static assets, or utility data.
6. Interactive widgets use hooks for local behavior and persistence.
7. Protected admin routes are gated by middleware/auth wrappers, with NextAuth handling session/auth logic.

In short, the app is architected as a modular admin UI platform:
- route groups define access and layout boundaries
- shared components provide the UI foundation
- contexts handle a few global interaction states
- hooks encapsulate local UI behavior
- utilities abstract auth, formatting, and browser persistence
- SCSS and assets provide a themeable design system

Main entry points: [`src/app/(admin)`](https://github.com/haroonalshaji/nexus_built/tree/HEAD/src/app/(admin)) (Feature slices), [`src/components/wrappers/AppProvidersWrapper.jsx`](https://github.com/haroonalshaji/nexus_built/blob/HEAD/src/components/wrappers/AppProvidersWrapper.jsx) (App providers), [`src/assets/scss/app.scss`](https://github.com/haroonalshaji/nexus_built/blob/HEAD/src/assets/scss/app.scss) (SCSS system), [`src/app/layout.jsx`](https://github.com/haroonalshaji/nexus_built/blob/HEAD/src/app/layout.jsx) (Root layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "App routes"
  root_layout["Root layout<br/>[layout.jsx]"]
  admin_layout["Admin layout<br/>protected layout<br/>[layout.jsx]"]
  admin_routes["Admin routes<br/>dashboard routes"]
  other_routes["Public routes"]
  admin_features["Feature slices<br/>route features"]
  public_features["Auth pages<br/>public features"]
end

subgraph "Shared system"
  providers["App providers<br/>provider wrapper"]
  auth_guard["Auth guard<br/>route protection"]
  layout_ctx["Layout state<br/>context"]
  chat_ctx["Chat state<br/>context<br/>[useChatContext.jsx]"]
  email_ctx["Email state<br/>context"]
  notif_ctx["Notify state<br/>context"]
  layout_components["Shell chrome<br/>layout components"]
  shared_ui["Shared UI<br/>ui kit"]
  hooks["UI hooks<br/>client hooks"]
  utils["Utilities<br/>helpers"]
end

subgraph "Assets & styles"
  static_data["Static data<br/>demo content"]
  styles["SCSS system<br/>style system<br/>[app.scss]"]
  images["Image assets<br/>media assets"]
end

subgraph "Auth API"
  api_auth["NextAuth API<br/>auth endpoint<br/>[[...nextauth]]"]
end

root_layout -->|"wraps"| providers
root_layout -->|"routes"| admin_routes
root_layout -->|"routes"| other_routes
admin_routes -->|"uses"| admin_layout
admin_layout -->|"composed of"| layout_components
admin_layout -->|"protected by"| auth_guard
auth_guard -->|"authenticates via"| api_auth
providers -->|"provides"| layout_ctx
providers -->|"provides"| chat_ctx
providers -->|"provides"| email_ctx
providers -->|"provides"| notif_ctx
admin_routes -->|"contains"| admin_features
other_routes -->|"contains"| public_features
admin_features -->|"uses"| shared_ui
admin_features -->|"uses"| hooks
admin_features -->|"uses"| utils
admin_features -->|"reads"| static_data
admin_features -->|"renders"| images
shared_ui -->|"styled by"| styles
layout_components -->|"styled by"| styles
public_features -->|"styled by"| styles
shared_ui -->|"uses"| utils
hooks -->|"extends"| utils
static_data -.->|"supports"| styles

click root_layout "https://github.com/haroonalshaji/nexus_built/blob/main/src/app/layout.jsx"
click admin_layout "https://github.com/haroonalshaji/nexus_built/blob/main/src/app/(admin)/layout.jsx"
click admin_routes "https://github.com/haroonalshaji/nexus_built/tree/main/src/app/(admin)"
click other_routes "https://github.com/haroonalshaji/nexus_built/tree/main/src/app/(other)"
click api_auth "https://github.com/haroonalshaji/nexus_built/blob/main/src/app/api/auth/[...nextauth]"
click providers "https://github.com/haroonalshaji/nexus_built/blob/main/src/components/wrappers/AppProvidersWrapper.jsx"
click auth_guard "https://github.com/haroonalshaji/nexus_built/blob/main/src/components/wrappers/AuthProtectionWrapper.jsx"
click layout_ctx "https://github.com/haroonalshaji/nexus_built/blob/main/src/context/useLayoutContext.jsx"
click chat_ctx "https://github.com/haroonalshaji/nexus_built/blob/main/src/context/useChatContext.jsx"
click email_ctx "https://github.com/haroonalshaji/nexus_built/blob/main/src/context/useEmailContext.jsx"
click notif_ctx "https://github.com/haroonalshaji/nexus_built/blob/main/src/context/useNotificationContext.jsx"
click layout_components "https://github.com/haroonalshaji/nexus_built/tree/main/src/components/layout"
click shared_ui "https://github.com/haroonalshaji/nexus_built/tree/main/src/components"
click hooks "https://github.com/haroonalshaji/nexus_built/tree/main/src/hooks"
click utils "https://github.com/haroonalshaji/nexus_built/tree/main/src/utils"
click static_data "https://github.com/haroonalshaji/nexus_built/tree/main/src/assets/data"
click styles "https://github.com/haroonalshaji/nexus_built/blob/main/src/assets/scss/app.scss"
click images "https://github.com/haroonalshaji/nexus_built/tree/main/src/assets/images"
click admin_features "https://github.com/haroonalshaji/nexus_built/tree/main/src/app/(admin)"
click public_features "https://github.com/haroonalshaji/nexus_built/tree/main/src/app/(other)"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class root_layout,admin_layout,admin_routes,other_routes,admin_features,public_features toneBlue
class providers,auth_guard,layout_ctx,chat_ctx,email_ctx,notif_ctx,layout_components,shared_ui,hooks,utils toneAmber
class static_data,styles,images toneMint
class api_auth toneRose
```

## Components

### App routes

Next.js route layer split into admin and public experiences.

- [Root layout](https://github.com/haroonalshaji/nexus_built/blob/HEAD/src/app/layout.jsx): next root layout · Global app shell and top-level composition. · `src/app/layout.jsx`
- [Admin layout](https://github.com/haroonalshaji/nexus_built/blob/HEAD/src/app/(admin)/layout.jsx): protected layout · Persistent shell for the main dashboard experience. · `src/app/(admin)/layout.jsx`
- [Admin routes](https://github.com/haroonalshaji/nexus_built/tree/HEAD/src/app/(admin)): dashboard routes · Primary route tree for dashboards, CRUD pages, and UI demos. · `src/app/(admin)`
- [Public routes](https://github.com/haroonalshaji/nexus_built/tree/HEAD/src/app/(other)): auth/public routes · Secondary route tree for auth, maintenance, and error pages. · `src/app/(other)`
- [Feature slices](https://github.com/haroonalshaji/nexus_built/tree/HEAD/src/app/(admin)): route features · Business-like modules such as dashboards, customers, property, agents, post, inbox, messages, charts, forms, tables, maps, widgets, and pages. · `src/app/(admin)`
- [Auth pages](https://github.com/haroonalshaji/nexus_built/tree/HEAD/src/app/(other)): public features · Sign-in, sign-up, reset password, lock screen, maintenance, coming soon, and error pages. · `src/app/(other)`

### Shared system

Reusable UI, wrappers, contexts, hooks, and utilities used across routes.

- [App providers](https://github.com/haroonalshaji/nexus_built/blob/HEAD/src/components/wrappers/AppProvidersWrapper.jsx): provider wrapper · Central React provider composition for global app state. · `src/components/wrappers/AppProvidersWrapper.jsx`
- [Auth guard](https://github.com/haroonalshaji/nexus_built/blob/HEAD/src/components/wrappers/AuthProtectionWrapper.jsx): route protection · Client-side protection and redirect wrapper for privileged areas. · `src/components/wrappers/AuthProtectionWrapper.jsx`
- [Layout state](https://github.com/haroonalshaji/nexus_built/blob/HEAD/src/context/useLayoutContext.jsx): context · Sidebar, theme, and shell interaction state. · `src/context/useLayoutContext.jsx`
- [Chat state](https://github.com/haroonalshaji/nexus_built/blob/HEAD/src/context/useChatContext.jsx): context · Shared messaging UI state. · `src/context/useChatContext.jsx`
- [Email state](https://github.com/haroonalshaji/nexus_built/blob/HEAD/src/context/useEmailContext.jsx): context · Inbox and mail UI state. · `src/context/useEmailContext.jsx`
- [Notify state](https://github.com/haroonalshaji/nexus_built/blob/HEAD/src/context/useNotificationContext.jsx): context · Notification and badge state. · `src/context/useNotificationContext.jsx`
- [Shell chrome](https://github.com/haroonalshaji/nexus_built/tree/HEAD/src/components/layout): layout components · Top bar, sidebar, footer, and global shell controls. · `src/components/layout`
- [Shared UI](https://github.com/haroonalshaji/nexus_built/tree/HEAD/src/components): ui kit · Reusable cards, modals, uploaders, tables, maps, and form inputs. · `src/components`
- [UI hooks](https://github.com/haroonalshaji/nexus_built/tree/HEAD/src/hooks): client hooks · Local interaction helpers for persistence, toggles, fetches, uploads, and viewport logic. · `src/hooks`
- [Utilities](https://github.com/haroonalshaji/nexus_built/tree/HEAD/src/utils): helpers · Auth, cookies, date, promise, layout, and API helper utilities. · `src/utils`

### Assets & styles

Static data, images, and SCSS design system.

- [Static data](https://github.com/haroonalshaji/nexus_built/tree/HEAD/src/assets/data): demo content · Menu items, product, task, social, and other local datasets. · `src/assets/data`
- [SCSS system](https://github.com/haroonalshaji/nexus_built/blob/HEAD/src/assets/scss/app.scss): style system · Theme, structure, page, plugin, and component styles. · `src/assets/scss/app.scss`
- [Image assets](https://github.com/haroonalshaji/nexus_built/tree/HEAD/src/assets/images): media assets · Brand, user, property, blog, and other static imagery. · `src/assets/images`

### Auth API

Explicit server-side authentication surface.

- [NextAuth API](https://github.com/haroonalshaji/nexus_built/blob/HEAD/src/app/api/auth/%5B...nextauth%5D): auth endpoint · Session and authentication route handler. · `src/app/api/auth/[...nextauth]`

## Connections

- Root layout → App providers: wraps · Root layout installs global providers.
- Root layout → Admin routes: routes · Admin subtree is mounted under the root app shell.
- Root layout → Public routes: routes · Public subtree is mounted under the root app shell.
- Admin routes → Admin layout: uses · Admin routes render within the admin shell.
- Admin layout → Shell chrome: composed of · Admin shell uses topbar, sidebar, and footer primitives.
- Admin layout → Auth guard: protected by · Protected dashboard experience is guarded.
- Auth guard → NextAuth API: authenticates via · Guard relies on NextAuth session state.
- App providers → Layout state: provides · Layout state is shared app-wide.
- App providers → Chat state: provides · Chat state is shared app-wide.
- App providers → Email state: provides · Email state is shared app-wide.
- App providers → Notify state: provides · Notification state is shared app-wide.
- Admin routes → Feature slices: contains · Main admin experience is feature-sliced.
- Public routes → Auth pages: contains · Secondary routes are auth and error flows.
- Feature slices → Shared UI: uses · Feature pages compose reusable UI building blocks.
- Feature slices → UI hooks: uses · Interactive pages rely on local behavior hooks.
- Feature slices → Utilities: uses · Features use utility helpers for auth, formatting, and persistence.
- Feature slices → Static data: reads · Many pages render from local demo datasets.
- Feature slices → Image assets: renders · Feature UIs use static imagery.
- Shared UI → SCSS system: styled by · Shared components depend on the SCSS system.
- Shell chrome → SCSS system: styled by · Shell chrome is themed through SCSS structure and config.
- Auth pages → SCSS system: styled by · Public/auth pages share the same styling system.
- Shared UI → Utilities: uses · Shared components lean on utility helpers.
- UI hooks → Utilities: extends · Hooks build on common utility logic.
- Static data → SCSS system: supports · Data-driven demos align with template styling and theming.
