Document ID   : DARX-TECH-ARCH-B-001
Title         : Daralbeida Multi-Entity Web Platform — Architecture Reference
Version       : 1.0
Status        : ACTIVE
Date Created  : 2026-06-03
Prepared by   : PYB / Daralbeida
Style         : BPGP
Department    : TECH
Classification: Internal
KB Category   : WEB-FRONTEND
Filename      : DARX_TECH_ARCHITECTURE_B_20260603.txt
Related Docs  : DARX-OPS-ADMIN-MANUAL-001, DARX-TECH-CAROUSEL-001

OUTLINE
--------------------------------------------------------------------------------

    1.  Purpose and Scope
    2.  Architecture at a Glance
    3.  Master Site
        3.1  Master Folder Layout
        3.2  Master Responsibilities
        3.3  Master Document Trunk
        3.4  Master Skin Trunk
        3.5  Master Image Trunk
        3.6  Master Site Manager
    4.  Entity Sites
        4.1  Entity Folder Layout
        4.2  Entity Responsibilities
        4.3  Entity Section Portals
        4.4  Entity Image Trunk
    5.  Shared CSV Registries
        5.1  Document Status Registry
        5.2  Skin Values Registry
    6.  Skin Cascade
    7.  Helpers and Constants
    8.  Filtering Mechanics
    9.  Mirror Environments
    10. Acronyms
    11. Glossary
    DOCUMENT CONTROL

--------------------------------------------------------------------------------

================================================================================
1. PURPOSE AND SCOPE
================================================================================

This document is the architecture reference for the Daralbeida multi-entity web
platform. It describes the master site, the entity sites, the document and skin
registries, the loading cascade, and the helpers that bind them together.

The reader is assumed to be the platform administrator or a developer joining
the project. Operating procedures (adding documents, adding entities, editing
skins) live in the companion administrator user manual; see DARX-OPS-ADMIN-
MANUAL-001.

In scope: the production folder model, the master/entity relationship, the
CSV-driven filter, the skin cascade, and the helper API. Out of scope: any
single page's design (covered in its own design record) and the consumer
homepage carousel (covered in DARX-TECH-CAROUSEL-001).


================================================================================
2. ARCHITECTURE AT A GLANCE
================================================================================

The platform is one master site plus N entity sites that share infrastructure
and document content but present a standalone face to visitors. The master is
the operator's cockpit; each entity site is a thin, themed view.

  Server root
  ├── 404.php, 403.php          shared error pages, only files in common at /
  ├── __darmaster/                 the cockpit and the single source of truth
  └── __darh/, __darx/, …       one folder per entity (Daralbeida-Holdings,
                                Daralbeida-X, Daralbeida-Mill, and any future
                                __dar* sibling)

A visitor never sees /__darmaster/ directly. The entity sites publish documents,
serve homepages, run carousels — everything visitor-facing — by reading from
the master.


================================================================================
3. MASTER SITE
================================================================================

3.1 MASTER FOLDER LAYOUT

The master site lives entirely under /__darmaster/ and has the following shape:

  /__darmaster/
     12/                       the site manager (admin UI)
        index.php              landing — tabs for Documents and Skins
        skins.php              skin values dashboard
     11/                       the document trunks
        0101/txt/              .txt flat trunk (BPGP knowledge base)
        0102/html/             .html flat trunk (legacy HTML docs)
     api/                      shared PHP libraries
        _base.php              DARMASTER_BASE + ENTITY constants, path helpers
        darx_helpers.php       darx_load_skin(), darx_img(),
                               darx_img_entity(), darx_render_skin_vars()
        doc_status.csv         per-document registry (see Section 5.1)
        skin_values.csv        per-entity/section skin variable registry
                               (see Section 5.2)
        module_section_scanner.php   the file scanner + CSV-driven filter
        module_nav_sections.php      the shared top nav module (PHP)
        doc_status_lib.php           CSV registry I/O
     css/
        base/                  unskinnable foundation; never per-entity
           tokens.css          global tokens (colours, spacing, type scale)
           nav.css             top nav module styling
           portal.css          section portal layout
        skins/                 entity-level and section-level skin overrides
           entity-darh.css     DARH skin (palette, wordmark, etc.)
           entity-darx.css     DARX skin
           entity-darm.css     DARM skin
           section-01.css      OPTIONAL — section-01 accents
           section-02.css      OPTIONAL — section-02 accents
           …
     img/                      ecosystem-wide images (see Section 3.5)
        certifications/        third-party cert logos (USDA, EU Bio, …)
        partners/              partner / retailer marks
        icons/                 generic UI icons
        flags/                 language flags
        shared/                anything cross-entity that fits nowhere above


3.2 MASTER RESPONSIBILITIES

The master site holds and controls everything that is shared across entities.
Specifically:

- The two flat document trunks (txt and html). Every document the platform
  publishes lives in one of these two folders. No copies, no per-entity
  duplicates.
- The shared PHP libraries (scanner, helpers, nav module, CSV I/O).
- The shared base CSS (tokens, nav module, portal layout).
- The entity and section skin layers (see Section 6).
- The ecosystem-wide image trunk (see Section 3.5).
- The site manager UI at /__darmaster/12/, which is the only place per-document
  metadata and per-entity skin values are edited.

The master site does not have public-facing portals of its own. /__darmaster/01/,
/__darmaster/02/, and friends do not exist. Visitors do not browse the master.


3.3 MASTER DOCUMENT TRUNK

All documents live in two flat directories:

  /__darmaster/11/0101/txt/        every published .txt
  /__darmaster/11/0102/html/       every published .html

There are no per-section subfolders and no per-entity subfolders inside these
trunks. A document's section, entity, status, and department are values in
the registry (see Section 5.1), not directory positions. Renaming a file does
not move it between sections; editing its CSV row does.

The filename convention is preserved for human navigation and for filename
parsing during the initial scan:

    ENTITY_CATEGORY_DESCRIPTOR_YYYYMMDD.ext

Underscores are the only separator. The date is the file's creation or
revision date (never copied from an older file). Examples:

    DARX_TECH_CAROUSEL_CHANGELOG_20260527.txt
    DARH_STDS_BPGP_202605301215.txt
    DARX_KB_RETAIL_CERTIFICATIONS_20260523.html


3.4 MASTER SKIN TRUNK

Each entity has one skin file in /__darmaster/css/skins/entity-<name>.css. Each
section may optionally have one in /__darmaster/css/skins/section-<NN>.css. The
entity skin defines the entity's identity (palette, wordmark, frame tones);
the section skin, if present, layers section-specific accents on top.

A skin file holds the STRUCTURAL CSS for the entity or section. Operator-
tweakable VALUES (colours, fonts, compactness, etc.) are stored separately
in /__darmaster/api/skin_values.csv and applied through a generated inline
<style> tag. See Section 6 for the full cascade.


3.5 MASTER IMAGE TRUNK

Ecosystem-wide images live under /__darmaster/img/. The decision rule for any
image is:

    If the image survives the entity, it belongs in master.
    If the image disappears when the entity does, it belongs in the entity.

Two mental tests cover every edge case:

  1. "If I delete /__darh/ tomorrow, is this image still needed by anyone
     else?" Yes → master. No → entity.

  2. "Does the image BELONG TO the entity, or is the entity merely USING it?"
     Belongs to → entity. Merely using → master.

Buckets under /__darmaster/img/:

  certifications/   USDA Organic, EU Bio, Kosher, Halal, Olive Japan,
                    Flos Olei, Mario Solinas, ISO marks, …
  partners/         partner / supplier / retailer marks
  icons/            generic UI icons (download, share, document-type SVGs)
  flags/            language flags for the switcher
  shared/           cross-entity decorative assets and system illustrations
                    (404 / 403 art, generic olive-branch SVGs, …)

When in doubt, err toward master.


3.6 MASTER SITE MANAGER

The master site manager is the admin UI at /__darmaster/12/index.php. It exposes
two tabs (and may grow):

- Documents tab. Lists every document in the trunks, and for each one lets
  the operator edit the registry row: entity, section, status, department,
  title overrides, etc.

- Skins tab. Loads /__darmaster/12/skins.php, which presents the skin values
  registry as form controls (see Section 5.2) per entity and per section.
  Saving writes back to skin_values.csv and bumps a shared cache token so
  every entity site picks up the change on its next request.


================================================================================
4. ENTITY SITES
================================================================================

4.1 ENTITY FOLDER LAYOUT

An entity site is a thin folder. The canonical shape (using DARH as the
example) is:

  /__darh/
     _entity.php              sets ENTITY = 'DARH', requires master helpers
     index.php                entity homepage (custom carousel content, etc.)
     01/index.php             section-01 portal — thin shim
     02/index.php             section-02 portal — thin shim
     …
     07/index.php             section-07 portal — thin shim
     img/                     entity-specific images (see Section 4.4)
        logo/
        favicon/
        hero/
        kc/
        marketing/

There is no /__darh/12/, no /__darh/11/, no /__darh/api/, no /__darh/css/.
Skins, content, and code all live in master.


4.2 ENTITY RESPONSIBILITIES

An entity site is responsible only for:

- The entity homepage (its public landing page, with whatever custom hero,
  carousel, or marketing it needs).
- Identifying itself to master by setting the ENTITY constant in _entity.php.
- Holding entity-specific images that intrinsically belong to it (its logo,
  its favicon set, its photography, its keycard imagery, its marketing
  visuals).

That is the entire entity-owned surface.


4.3 ENTITY SECTION PORTALS

Each section portal under an entity (e.g. /__darh/02/index.php) is a thin
shim. The portal does not contain layout, scanner code, or filter logic; it
just identifies itself to the shared portal renderer and lets master handle
the rest. The canonical shim is approximately:

    <?php
    require_once __DIR__ . '/../_entity.php';
    $section = basename(__DIR__);
    require DARMASTER_BASE . 'api/render_portal.php';

That is ten lines including the closing PHP tag. Section number is derived
from the folder name (self-correcting); entity is set by _entity.php. The
portal renderer reads the document registry, filters by (entity AND section
AND status = public), loads the correct skin cascade, and emits the page.


4.4 ENTITY IMAGE TRUNK

Each entity has an /img/ folder for images that intrinsically belong to it.
Suggested subdivision:

  /__darh/img/
     logo/                    DARH wordmark and monogram variants
     favicon/                 DARH favicon set (.ico, .svg, .png 192/180)
     hero/                    DARH-branded hero photography
     kc/                      DARH keycard carousel images
     marketing/               DARH-branded marketing visuals

The decision rule is the same as Section 3.5, applied per image: if it
survives the entity, it goes in master; if it disappears with the entity,
it goes here.


================================================================================
5. SHARED CSV REGISTRIES
================================================================================

5.1 DOCUMENT STATUS REGISTRY

File:    /__darmaster/api/doc_status.csv
Editor:  /__darmaster/12/index.php (Documents tab)
Owner:   shared (every entity reads it; only master edits it)

The registry is the system of record for per-document control values. Each
file scanned in /__darmaster/11/0101/txt/ or /__darmaster/11/0102/html/ has exactly
one row, keyed by filename. The columns the platform reads at filter time
are:

  filename     the file's name (key)
  doc_uid      stable id minted on first registration (e.g. DARX-DOC-0042)
  entity       the entity code, or a list, or "shared":
                 DARH                 → appears on /__darh/ only
                 DARX,DARM            → appears on both
                 shared               → appears on every entity site
  section      the section number (01..07) where the doc should appear
  status       1 = public (visible on portals), 0 = private (hidden)
  dept         the org function tag (TECH, OPS, STDS, KB, …)

Additional columns (title, version, dates, size, line/char counts, purpose
snippet, etc.) carry rich metadata and may be displayed by the portals but
are not part of the filter logic.

An entity section portal at /__entityA/NN/ shows only rows where:

    status == 1
    AND ( entity == ENTITY OR entity contains ENTITY OR entity == 'shared' )
    AND section == NN


5.2 SKIN VALUES REGISTRY

File:    /__darmaster/api/skin_values.csv
Editor:  /__darmaster/12/skins.php (Skins tab)
Owner:   shared (every entity reads it; only master edits it)

The registry holds operator-tweakable visual values. Each row is one
(scope, variable, value) triple. Scopes are either an entity code, a section
code, or the special scope "global". Variables are CSS custom property names
(without the leading double dash). Examples:

    scope        variable          value
    global       gold              #B8832A
    global       brand-dark        #1C1410
    global       font-display      'Cinzel Decorative', Georgia, serif
    DARH         brand-primary     #2B4D7A
    DARH         brand-accent      #C7A04E
    DARH         compactness       normal
    DARX         brand-primary     #46331E
    DARX         brand-accent      #D8A845
    section-02   accent            #6B3A1A

The renderer emits one inline <style> tag per page that defines :root CSS
variables in this precedence order:

    global  <  entity (current page's entity)  <  section (current page's
                                                            section)

Later rules win, so a section value overrides an entity value, which
overrides a global value.

Controls exposed in the dashboard (initial set):

  Colours        brand-primary, brand-accent, gold, mat-color, text-color,
                 bg-color, link-color
  Typography     font-display (wordmark), font-body, font-mono,
                 base-size, scale-ratio
  Compactness    padding-scale (compact / normal / spacious),
                 gap-scale (tight / normal / loose)
  Surface        shadow-intensity (none / subtle / strong)
  Wordmark       wordmark-letter-spacing

The dashboard may grow over time; new columns added to skin_values.csv are
read by the renderer automatically.


================================================================================
6. SKIN CASCADE
================================================================================

Every page served by an entity site loads the following stylesheets and
inline style, in this fixed order:

    1. /__darmaster/css/base/tokens.css           global tokens
    2. /__darmaster/css/base/nav.css              shared nav module
    3. /__darmaster/css/base/portal.css           shared portal layout
    4. /__darmaster/css/skins/entity-<NAME>.css   entity skin file
    5. /__darmaster/css/skins/section-<NN>.css    section skin file (if exists)
    6. <style> tag generated from skin_values.csv for the current
       (entity, section) combination, defining :root custom properties
       in (global → entity → section) order

Later rules win, so the cascade is deterministic. The structural skin files
(steps 4 and 5) are CSS edited by a developer; the values inline (step 6)
are edited by the operator through the dashboard.

The helper darx_load_skin($entity, $section) emits steps 1 through 6 in one
call and is the only thing an entity page needs to render the cascade
correctly. See Section 7.


================================================================================
7. HELPERS AND CONSTANTS
================================================================================

The shared helper library is /__darmaster/api/darx_helpers.php. It defines:

  DARMASTER_BASE
      The path to /__darmaster/ for the current request, with a trailing slash.
      Auto-detected from $_SERVER['SCRIPT_NAME'], so it resolves correctly
      under /_devt/__darmaster/ in dev and /_prod/__darmaster/ in prod. Pairs
      with SITE_BASE from the existing _base.php for the legacy consumer
      homepage.

  ENTITY
      The entity code for the current site, e.g. 'DARH'. Defined by
      /__entityA/_entity.php before master code runs. The portal renderer
      and darx_load_skin() read this constant.

  darx_load_skin(string $entity, string $section): void
      Emits the six-step skin cascade for the given (entity, section).
      Always called from inside <head>.

  darx_img(string $relative): string
      Returns the URL of an image in the master image trunk. Example:
        darx_img('certifications/usda-organic.svg')
            → '/_devt/__darmaster/img/certifications/usda-organic.svg'

  darx_img_entity(string $relative): string
      Returns the URL of an image in the current entity's image trunk.
      Example, on /__darh/:
        darx_img_entity('logo/wordmark.svg')
            → '/_devt/__darh/img/logo/wordmark.svg'

  darx_render_skin_vars(string $entity, string $section): string
      Returns the inline <style>:root{…}</style> tag for step 6 of the
      cascade. Used internally by darx_load_skin(); also callable directly
      for testing.


================================================================================
8. FILTERING MECHANICS
================================================================================

The section portal renderer follows three steps per request:

  Step 1 — SCAN
    darx_scan_all() reads the two flat trunks and returns one row per
    document, with metadata parsed from the filename (entity, dept,
    descriptor, date) and the filesystem (size, lines, chars, version).

  Step 2 — JOIN
    Each scanned row is joined with its registry row from doc_status.csv
    (keyed by filename). Registry values override filename-parsed values
    where both exist. The entity, section, and status columns from the
    registry become authoritative for filtering.

  Step 3 — FILTER
    The renderer keeps only rows where:
        status == 1
        AND ( entity matches ENTITY OR entity == 'shared' )
        AND section == basename(__DIR__)

    Then it sorts by (entity, category, filename) and emits the page in two
    views (HTML and TXT) per the shared portal layout.

Documents in the trunk that have no registry row are auto-registered with
default values (status = 0, entity inferred from filename token, section
inferred from the legacy filename-to-section map if present, otherwise '07').
They are private by default and do not appear on any portal until the
operator publishes them in the dashboard.


================================================================================
9. MIRROR ENVIRONMENTS
================================================================================

The domain redirects / to either /_devt/ (dev) or /_prod/ (prod). Each
mirror contains its own copy of the entire tree:

  /_devt/__darmaster/, /_devt/__darh/, /_devt/__darx/, /_devt/__darm/, …
  /_prod/__darmaster/, /_prod/__darh/, /_prod/__darx/, /_prod/__darm/, …

All paths inside the platform are written with SITE_BASE or DARMASTER_BASE so
the same source serves both mirrors with no hardcoded mirror folder. See
DARX-TECH-CAROUSEL-001 Section 7 for the mirror-portability conventions.

Deploying to production is a sync from /_devt/ to /_prod/ once changes have
been verified in dev.


================================================================================
10. ACRONYMS
================================================================================

The following acronyms appear in this document:

Acronym   Expansion
────────  ────────────────────────────────────────────
BPGP      Bullet-Proof Ground-Plane
CSS       Cascading Style Sheets
CSV       Comma-Separated Values
DARH      Daralbeida Holdings
DARM      Daralbeida Mill
DARX      Daralbeida-X
KB        Knowledge Base
PHP       PHP: Hypertext Preprocessor
SVG       Scalable Vector Graphics
UI        User Interface
URL       Uniform Resource Locator


================================================================================
11. GLOSSARY
================================================================================

Key terms used in this document:

Term               Definition
─────────────────  ──────────────────────────────────────────────────────
Cascade            The fixed order in which stylesheets and values load.
Entity             A first-class brand or org unit with its own site.
Entity site        A standalone-feeling website under /__darh/, /__darx/, …
Master             The cockpit at /__darmaster/; single source of truth.
Mirror             A deployment copy: /_devt/ for dev, /_prod/ for prod.
Portal             A section page that lists documents from the trunk.
Registry           A CSV that is read by code and edited only via the UI.
Section            A numbered domain (01..07) — Company, Market, etc.
Shim               A thin entity-side file that defers to master.
Skin               A CSS layer that gives an entity or section its identity.
Trunk              A flat directory: the document or image store.


DOCUMENT CONTROL
Document ID   : DARX-TECH-ARCH-B-001
Title         : Daralbeida Multi-Entity Web Platform — Architecture Reference
Version       : 1.0
Status        : ACTIVE
Style         : BPGP
Department    : TECH
Date Created  : 2026-06-03
Date Revised  : 2026-06-03
Last Modified : 2026-06-03
KB Category   : WEB-FRONTEND
Filename      : DARX_TECH_ARCHITECTURE_B_20260603.txt
Review Cycle  : On next platform structural change.
Retention     : Life of the platform plus two years.
Owner         : PYB / Daralbeida
Distribution  : Daralbeida web engineering and platform operators.
COMPLIANCE    : Single source of truth at /__darmaster/; entities read, not own.

Revision History:
Ver    Date          Summary of Changes
1.0    2026-06-03    Initial issue defining Structure B.

END OF DOCUMENT