File Linking Relationships - humanbit-dev-org/templates GitHub Wiki

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
β”‚
β”œβ”€β”€ .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
β”‚   β”‚
β”‚   β”œβ”€β”€ public/                     β†’ Static files that are served directly to the browser
β”‚   β”‚   β”œβ”€β”€ favicon/                β†’ Icons used for browser tabs and bookmarks
β”‚   β”‚   β”œβ”€β”€ fonts/                  β†’ Licensed or external fonts (not served by Google Fonts)
β”‚   β”‚   β”œβ”€β”€ images/                 β†’ Pictures used across the site
β”‚   β”‚   β”œβ”€β”€ videos/                 β†’ Video files used across the site
β”‚   β”‚   └── js/                     β†’ JavaScript libs and files that run outside the Next.js lifecycle
β”‚   β”‚
β”‚   β”œβ”€β”€ src/                        β†’ Core source code of the application
β”‚   β”‚   β”‚
β”‚   β”‚   β”œβ”€β”€ app/[lang]/             β†’ Next.js routes, layouts, and middleware for handling pages by language
β”‚   β”‚   β”‚   β”œβ”€β”€ dictionaries.js/    β†’ Load translations at runtime, based on the language in the route
β”‚   β”‚   β”‚   β”œβ”€β”€ layout.js           β†’ Root layout file that wraps the entire app's UI
β”‚   β”‚   β”‚   β”œβ”€β”€ loading.js/         β†’ Fallback UI shown while a page is loading
β”‚   β”‚   β”‚   β”œβ”€β”€ page.js             β†’ Page component for the current route
β”‚   β”‚   β”‚   └── ...                 β†’ 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
β”‚   β”‚   β”‚
β”‚   β”‚   β”œβ”€β”€ config/                 β†’ Project-wide constants
β”‚   β”‚   β”‚   └── settings.js         β†’ Global app settings (e.g., theme, language options)
β”‚   β”‚   β”‚
β”‚   β”‚   β”œβ”€β”€ hooks/                  β†’ Reusable functions that get information while the user is interacting with the site
β”‚   β”‚   β”‚   β”œβ”€β”€ useAuth.js          β†’ Handles authentication state
β”‚   β”‚   β”‚   β”œβ”€β”€ useSectionScroll.js β†’ Scroll-based navigation logic
β”‚   β”‚   β”‚   β”œβ”€β”€ useTheme.js         β†’ Manages dark/light theme switching
β”‚   β”‚   β”‚   └── ...                 β†’ Any other custom hooks
β”‚   β”‚   β”‚
β”‚   β”‚   β”œβ”€β”€ lib/                    β†’ Functions that run on the server to get info before rendering the page
β”‚   β”‚   β”‚   β”œβ”€β”€ server/             β†’ Server-only versions of helpers for handling data before the page loads
β”‚   β”‚   β”‚   β”œβ”€β”€ 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
β”‚   β”‚   β”‚   β”œβ”€β”€ 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
β”‚   β”‚   β”‚   β”œβ”€β”€ ThemeProvider.js    β†’ Manages global theme state
β”‚   β”‚   β”‚   └── ...                 β†’ Any other global providers
β”‚   β”‚   β”‚
β”‚   β”‚   β”œβ”€β”€ utils/                  β†’ General helper functions and internal libraries (non-React utilities)
β”‚   β”‚   β”‚   β”œβ”€β”€ 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
β”‚   β”œβ”€β”€ .gitignore                  β†’ Files and folders Git should ignore
β”‚   β”œβ”€β”€ .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
β”‚
β”œβ”€β”€ .gitattributes                  β†’ Settings for Git handling of files
β”œβ”€β”€ .gitignore                      β†’ Lists files and folders Git should ignore
β”œβ”€β”€ LICENSE                         β†’ License terms for using and sharing the project
└── README.md                       β†’ Project overview and usage instructions

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)
⚠️ **GitHub.com Fallback** ⚠️