Skip to content

File Linking Relationships

Jump to bottom
G. Silveri edited this page Feb 23, 2026 · 18 revisions

In order to split code into logical blocks, the relationship structure between files is as follows.

Files are indented with four spaces, configured to the tab key.

Directory tree view

 
codebase/                                → The root directory containing all project code, configuration, and system documentation
│
├── .git/                                → Local Git repository data (history, refs, objects)
│
├── .github/                             → GitHub-specific configuration (e.g., issue templates, workflows, community files)
│
├── backend/                             → Full Laravel (API-only) project with routes, domain logic, migrations, tests, and a Backpack admin panel
│
├── docs/                                → Internal notes for system behavior, architecture, and implementation details
│
├── frontend/                            → Next.js application with pages, components, configs, and supporting utilities
│   │
│   ├── .next/                           → Folder where Next.js puts files it builds to run the app
│   │
│   ├── cache/                           → Temporary files used to speed up builds and development tools
│   │
│   ├── lang/                            → JSON files with translations used for multi-language support across the app
│   │   └── .gitkeep                     → Keeps the otherwise-empty folder in Git (placeholder file)
│   │
│   ├── public/                          → Static files that are served directly to the browser
│   │   ├── favicon/                     → Icons used for browser tabs and bookmarks
│   │   ├── fonts/                       → Licensed or external fonts
│   │   │   └── .gitkeep                 → Keeps the otherwise-empty folder in Git (placeholder file)
│   │   ├── images/                      → Pictures used across the site
│   │   ├── js/                          → JavaScript libs and files that run outside the Next.js lifecycle
│   │   └── videos/                      → Placeholder video files used across the site as mockups
│   │
│   ├── src/                             → Core source code of the application
│   │   │
│   │   ├── app/[lang]/                  → Next.js routes, layouts, and middleware for handling pages by language
│   │   │   ├── (boilerplate)/           → Template route group for layout and tenant patterns (does not affect URL path)
│   │   │   ├── dictionaries.js/         → Load translations at runtime, based on the language in the route
│   │   │   ├── globals.scss             → Global stylesheet entry point (site-wide styles loaded once)
│   │   │   ├── layout.js                → Root layout file that wraps the entire app's UI
│   │   │   ├── layout.scss              → Styles scoped to the root layout shell (structure-level layout styling)
│   │   │   ├── loading.js/              → Fallback UI shown while a page is loading
│   │   │   └── ...                      → Additional app-related files
│   │   │
│   │   ├── assets/                      → Style and design resources
│   │   │   ├── bessex/                  → bEssEx (Bootstrap fork)
│   │   │   ├── css/                     → External CSS libraries (including Tailwind entry point)
│   │   │   └── scss/                    → Custom SCSS engine (variables, mixins, etc.)
│   │   │
│   │   ├── components/                  → Reusable UI components
│   │   │   ├── alerts/                  → User-facing alerts and notifications
│   │   │   │   ├── events/              → Alerts for general events (not tied to user profile)
│   │   │   │   └── registration/        → Alerts for profile updates and registration actions
│   │   │   ├── blocks/                  → Self-contained blocks of reusable UI
│   │   │   ├── dialogs/                 → Interactive prompts such as modals and forms
│   │   │   ├── elements/                → Small, granular UI elements
│   │   │   ├── footers/                 → Footer components
│   │   │   ├── navbars/                 → Navigation-related components
│   │   │   └── TenantReference/         → Template tenant component (module and feature-level implementation example)
│   │   │
│   │   ├── config/                      → Application-level configuration and integration setup
│   │   │   ├── constants.js             → Environment-backed app constants (URLs, locales, shared paths)
│   │   │   ├── favicon-generator.js     → Next.js favicon and web app metadata generator
│   │   │   ├── fonts-loader.js          → `next/font` configuration (Google fonts and local-font entry point)
│   │   │   ├── global-scripts.jsx       → Client-side global script/bootstrap initializer and cleanup on navigation
│   │   │   ├── klaro-config.js          → Klaro consent configuration (translations, services, defaults)
│   │   │   ├── klaro-cookie-consent.jsx → Klaro setup wrapper component (runs Klaro.setup with provided config)
│   │   │   ├── metadata-setup.js        → Metadata composition entry point (SEO + favicons; exports loaders/scripts)
│   │   │   ├── seo-manager.js           → Builds structured SEO metadata from backend metadata JSON + fallbacks
│   │   │   └── stylesheets-importer.js  → Central stylesheet import list (Tailwind, bEssEx, globals, app SCSS, FA)
│   │   │
│   │   ├── hooks/                       → Reusable functions that get information while the user is interacting with the website
│   │   │   ├── custom/                  → App-specific implementations (outside the base template structure)
│   │   │   ├── tenantFeatures.js        → Tenant feature flag evaluation and helper utilities
│   │   │   ├── useAuth.js               → Handles authentication state
│   │   │   ├── useSectionScroll.js      → Scroll-based navigation logic
│   │   │   ├── useTheme.js              → Manages dark/light theme switching
│   │   │   └── ...                      → Any other custom hooks
│   │   │
│   │   ├── lib/                         → Internal SSR library functions that run on the server to get info before rendering
│   │   │   ├── custom/                  → App-specific implementations (outside the base template structure)
│   │   │   ├── server/                  → Grouped server-side utilities (expanded when a concern spans multiple files)
│   │   │   ├── tenant/                  → Tenant resolution and module/feature registry utilities
│   │   │   ├── server.js                → Entry point that loads all server-side utilities in one place for easy access
│   │   │   ├── auth.js                  → Authentication-related API calls
│   │   │   ├── stripe.js                → Payment processing integration
│   │   │   └── ...                      → Other third-party integrations
│   │   │
│   │   ├── providers/                   → Components that make data available to multiple parts of the app through context
│   │   │   ├── custom/                  → App-specific implementations (outside the base template structure)
│   │   │   ├── Api.js                   → Centralized API client wrapper for backend communication
│   │   │   ├── App.js                   → Root application composition wrapper (global providers and setup)
│   │   │   ├── AuthProvider.js          → Provides authentication context
│   │   │   ├── Client.js                → Wraps all hooks so their data can be used anywhere in the app
│   │   │   ├── ContentProvider.js       → Centralized content management
│   │   │   ├── Tenant.js                → Tenant resolution and runtime access helper (active tenant context)
│   │   │   ├── ThemeProvider.js         → Manages global theme state
│   │   │   └── ...                      → Any other global providers
│   │   │
│   │   ├── utils/                       → Global utilities independent of React and Next.js lifecycle
│   │   │   ├── animations/              → Internal animation scripts bundled as part of the app for easy access
│   │   │   ├── helpers/                 → Generic utility functions shared across the app
│   │   │   ├── manual/                  → One-off scripts invoked manually, not part of the main bundle
│   │   │   │   ├── custom/              → Project-specific ad hoc scripts
│   │   │   │   └── standalone/          → Scoped scripts loaded individually when needed, not included globally
│   │   │   ├── formatDate.js            → Formats dates into readable formats
│   │   │   ├── debounce.js              → Prevents excessive function calls
│   │   │   ├── fetchData.js             → Simplifies API requests
│   │   │   ├── domHelpers.js            → Functions for DOM manipulation
│   │   │   └── ...                      → Other non-React utility functions
│   │   │
│   │   └── middleware.js                → Middleware logic that runs on every request to control redirects, authentication, or other request handling
│   │
│   ├── .env.local                       → Local environment variables like API keys, secrets, and base URLs
│   ├── .prettierignore                  → Files and folders Prettier should skip formatting
│   ├── .prettierrc                      → Rules for Prettier code formatting
│   ├── next-env.d.ts                    → Auto-generated TypeScript definitions for Next.js
│   ├── next.config.mjs                  → Next.js configuration file for routing, builds, images, and other framework settings
│   ├── package.json                     → Lists project dependencies, scripts, and metadata
│   ├── pnpm-lock.yaml                   → Locked package versions for consistent installs
│   ├── postcss.config.mjs               → Configuration for PostCSS (used by Tailwind)
│   ├── rollup.config.mjs                → Configuration for Rollup, a bundler that compiles all internal scripts into a single file
│   └── tsconfig.json                    → TypeScript configuration for module paths, type checking, and compiler behavior in the project
│
├── tenants                              → Tenant configuration schema and flag registry (modules and features)
│   ├── flags.md                         → Documents the tenant schema and how modules/features gate behavior
│   └── flags.json                       → All tenant flags (default values for modules and feature toggles)
│
├── .gitattributes                       → Settings for Git handling of files
├── .gitignore                           → Files and folders Git should ignore
├── LICENSE                              → License terms for using and sharing the project
└── README.md                            → Project overview and usage instructions

Note:
  In `/hooks`, `/lib`, and `/providers`, folders are introduced only when a single concern expands into multiple related files.
  Otherwise, features remain as single files.

JavaScript & JSX

All related files are stored in the frontend folder:

  • Static assets, such as favicon, fonts, videos, and external scripts that need to be accessible to the public at a fixed URL are placed in the public folder.
  • Local files, including pages, components, and styles, are kept within the src folder (which is optional but common for organizing the source code).

Next.js's <Image /> component is highly effective at optimizing images, so placing images in the src folder allows them to take advantage of automatic optimization (like lazy loading, resizing, and serving in modern formats like WebP), which isn't possible if they're in the public folder.

External structure

For best practice, use .js for pages and .jsx for components (though both extensions are interchangeable).

The structure also supports .ts and .tsx versions out-of-the-box, as the router and aliases have been adapted for seamless use with both JavaScript and TypeScript.

  1. Next.js's App Router (available from version 13) uses layout.js as its top-level entry point, meaning that it's where the shared UI is placed. It contains:

    1. Fonts (applied to the <html> tag via CSS variables)

    2. HeadComponent.jsx (spreads <head> components into the metadata object)

      • Favicon
      • Scripts
      • SEO
      • Stylesheets

    3. RootLayout component (used to define the <html> and <body> tags and other globally shared UI)

    4. Outer wrapper classes:

      ```
<body className="bg_color_white fx_load" />
    <div className="container_humanbit_overflow scrollbar_spacing" id="page" />
        <div className="container_humanbit_structure container-fluid" />
```

    5. children (required) and params (optional) props

  2. page.js (routes to the website's home page)

  3. page.module.css/page.module.scss (Next.js's built-in CSS/Sass compiler)

    Next.js supports Sass Modules, which locally scope styles to components by compiling SCSS to CSS and dynamically injecting the styles into the page's <style> tag at runtime. This prevents style conflicts and optimizes CSS for both development (with hot reloading) and production (with minimized, tree-shaken styles). Global SCSS files are compiled into a separate CSS file in production.

    Tree-shaking ensures that only the CSS used by the current page or component is loaded.

  4. globals.css/globals.scss

  5. folders: app, components, hooks, styles

  6. src/public

  7. routes/aliases, can use JS and TSX together out-of-the-box

  8. The only way a script file can be diretly included in Next.js is when placed on the public folder.


Internal structure

Just as most things in JavaScript are handled as objects (even primitives behave like objects when accessed via methods), in JSX, every element or include can be considered a component—including pages.

An object is a collection of key-value pairs, where keys are strings (or symbols) and values can be any data type, including functions

  1. ES6 Module Exports #

    • Default Exports: Pages in Next.js must use default exports, as Next.js automatically looks for these in the pages or app directory to render components.

    • Named Exports: For components, named exports are used for naming consistency across the project, although either type is allowed.

  2. return statement

    • return ( ... ); is typically used when returning JSX elements (as in an HTML-like structure) within a component.
    • return { ... }; commonly used when returning an object from a function or method, possibly containing multiple key-value pairs.

Use <Script /> in Next.js when you need to:

Load external JS libraries (e.g. Stripe, Google Maps, Analytics)

Inject inline scripts (e.g. for tracking or widgets)

Control load timing (beforeInteractive, afterInteractive, etc.)

✅ Client-side only ❌ Not for app logic or server data processing

In JSX ternaries, that looks like this:

{condition1 ? (
  // A
) : condition2 ? (
  condition2_1 ? (
    // B
  ) : condition2_2 ? (
    // C
  ) : (
    // fallback for condition2
  )
) : condition3 ? (
  // D
) : (
  // final else
)}

That directly mirrors:

if (condition1) {
  // A
} else if (condition2) {
  if (condition2_1) {
    // B
  } else if (condition2_2) {
    // C
  } else {
    // fallback for condition2
  }
} else if (condition3) {
  // D
} else {
  // final else
}

Global Provider – Quick Manual

1️⃣ Create the Provider

  • Location: /providers/GlobalProvider.jsx
  • Purpose: Stores global state & shared API data
  • Includes: useState for data, createContext, and useContext 
"use client";
import { createContext, useContext, useState } from "react";

const GlobalContext = createContext();

export function GlobalProvider({ children }) {
  const [globalState, setGlobalState] = useState({});
  const [apiData, setApiData] = useState(null);

  return (
    <GlobalContext.Provider value={{ globalState, setGlobalState, apiData, setApiData }}>
      {children}
    </GlobalContext.Provider>
  );
}

export function useGlobalContext() {
  return useContext(GlobalContext);
}

2️⃣ Add It to Root Layout

  • Location: /app/[lang]/layout.js
  • Wraps <GlobalProvider> around children
import { GlobalProvider } from "@/providers/GlobalProvider";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <GlobalProvider>{children}</GlobalProvider>
      </body>
    </html>
  );
}

3️⃣ Use It in Any Component

  • Import & call useGlobalContext()
  • Read & update state
import { useGlobalContext } from "@/providers/GlobalProvider";

export default function MyComponent() {
  const { globalState, setGlobalState } = useGlobalContext();

  return <button onClick={() => setGlobalState({ clicked: true })}>Click</button>;
}

🔹 Summary

✅ Store state & API data in GlobalProvider.jsx
✅ Wrap the app in GlobalProvider (inside layout.js)
✅ Access it anywhere with useGlobalContext()

Done. No prop drilling, global state available anywhere. 🚀

Sass (SCSS)

All related files can be found within the static folder.

External structure

  1. A general upper-level entry point file (style.scss) calls (through the scoped loader @use rule) all mid-level controllers and acts as the sole compiling source.

  2. Four mid-level controllers (pages [_partials.scss], modules [_extends.scss], _mixins.scss and _variables.scss [the two latter combined into _dynamics.scss]) that @forward all the single files to style.scss for compilation.

  3. All the lower-level single files of each component type (pages [partials], extends [modules], mixins and _variables.scss) in which the style is actually written.

NOTE¹: The scoped @use rule is encouraged by the Sass team rather than the global @import rule that will soon be deprecated due to its numerous conflicting issues.
NOTE²: Since they're part of the main page structure, navigation bar, footer and general style modules are placed within the pages folder (partials) and called on the pages controller (_partials.scss) even though they're modular components, for intuitive display.


Internal structure

Different file types must call different controllers.
That is because since the @use rule is scoped, it's fundamentally impossible to globally relate all files to each other from a single high-level entry point as it would send them into a loop.
This was intended to avoid unexpected interactions, such as not being able to call mixins on a contained context.

  1. partials files call the _extends.scss and _dynamics.scss controllers.

  2. modules files call the _dynamics.scss controller.

  3. mixins files call the _variables.scss controller.


Favicon Guide

Generate here: RealFaviconGenerator

Recommended Source Image

  • Format: SVG (best) or PNG
  • SVG → Scales perfectly (512x512px+ recommended)
  • PNG → Use at least 512x512px (1024x1024px preferred)
  • Proportions: Square (1:1 ratio)

Clone this wiki locally