Overview

This repository contains the source code for the Miagati website, implemented as a client-side single-page application (SPA) with modular HTML fragments and JavaScript page controllers. The site emphasizes staged rendering, deterministic cleanup, and configuration-driven content for pricing, galleries, and background imagery.

The project is intended to be viewed and evaluated as a polished portfolio and production-style front-end codebase. It is not designed for reuse as a general-purpose template.

Features

• SPA navigation with staged fragment loading and lifecycle-managed page controllers.
• Modular components (header, footer, background, logo) loaded at runtime.
• Configuration-driven content from JSON and markdown sources.
• Script and command registries to avoid duplicate loads and enable debug tooling.
• Gallery and background features powered by structured configuration data.

Tech Stack

• HTML5 and CSS3 (modular stylesheets per feature/page)
• Vanilla JavaScript (ES modules, fetch-based fragment loading)
• LocalStorage for runtime toggles
• Font Awesome (CDN)
• SwiperJS (CDN)
• Marked (local copy for markdown rendering)

Architecture (High Level)

The application bootstraps from index.html, which loads js/app/App.js. At startup:

• IncludeHtmlLoader resolves include-html attributes for shared components.
• PageManager manages SPA navigation and hash-based routing.
• PageRegistry loads page controllers on demand.
• FragmentLoader fetches and stages HTML fragments, executes scripts, and handles cleanup.

This structure keeps layout components persistent while swapping page fragments into #content-area.

How the SPA Works

1. Navigation buttons specify a data-page target.
2. PageManager requests the page controller via PageRegistry.
3. FragmentLoader fetches the fragment and prepares a staging DOM.
4. The controller initializes and validates the staging content.
5. The fragment commits into #content-area, the URL hash is updated, and the page title is set.
6. Cleanup hooks run when navigating away to prevent stale event handlers or scripts.

Project Structure

• index.html -- entry point and dependency wiring
• html/component/ -- shared fragments (header, footer, background, logo)
• html/page/ -- SPA page fragments (pricing, terms-of-service, gallery)
• js/app/ -- app orchestration and SPA routing
• js/core/ -- fragment loading, registries, and utilities
• js/pages/ -- page controllers and lifecycle hooks
• css/ -- global and page-specific styles
• data/config/ -- source JSON configuration inputs (pricing, gallery, background)
• data/markdown/ -- markdown content rendered at runtime
• docs/ -- architecture and development documentation

Documentation Links

• Architecture: docs/Architecture.md
• Developer Manual: docs/Developer-Manual.md
• Configuration Guide: docs/Configuration-Guide.md
• License: LICENSE.md

JSON Schemas

• Build and content config schemas are in schemas/.
• Editor mappings for config files are in .vscode/settings.json.
• scripts/build-config.json and all source files in data/config/ include inline $schema references.

Development Notes

• Serve the project with a local static file server so ES modules and fetch requests work correctly.
• Opening via file:// is not supported due to browser security restrictions.
• The app now expects a generated runtime config (/data/config/runtime-config.json), so run the build pipeline before serving production-like output.
• External dependencies load via CDN, and markdown rendering uses a local lib/marked.min.js.

Production Build (Cache Busting)

Build a deployable static output in dist/ with cache-busted JS/CSS URLs in index.html.

1. Run:

   npm install
   npm run build

2. Deploy the contents of dist/.

Alternative (auto-installs local Node/npm if missing):

python3 scripts/bootstrap_build.py

# Or alternatively:

python scripts/bootstrap_build.py

Run Docker dev container (detached by default):

python scripts/bootstrap_build.py --run-dev

Run Docker dev container in attached mode:

python3 scripts/bootstrap_build.py --run-dev --attached

Build behavior:

• BUILD_ID is generated automatically at build time.
• Resolution order: BUILD_ID environment variable -> git short commit hash -> UTC timestamp.
• Build logging uses loglevel with BUILD_LOG_LEVEL support (trace|debug|info|warn|error|silent).
• Set BUILD_DEBUG=1 for verbose debug output (equivalent to BUILD_LOG_LEVEL=debug when no explicit level is set).
• npm run build auto-installs required npm runtime packages when missing (set BUILD_SKIP_NPM_INSTALL=1 or SKIP_NPM_INSTALL=1 to disable this behavior).
• Local CSS files are bundled and minified per HTML entry in dist/ (for this project: dist/index.html -> dist/css/index.bundle.min.css), while CDN stylesheets remain unchanged.
• Non-minified copied CSS files in dist/css/ are removed during build; only minified bundle outputs remain there.
• HTML, JS, and JSON outputs in dist/ are minified during the asset optimization stage.
• Every local .js and .css URL in built HTML files receives or updates ?v=<BUILD_ID>.
• All data/config/*.json sources are merged into dist/data/config/runtime-config.json.
• Gallery and background images are processed into optimized WebP variants during build, with metadata injected into runtime-config.json.
• Watermarking is rule-driven via scripts/build-config.json (imagePipeline.watermark) and currently applies by default to gallery spotlight and gallery original (download) assets using scripts/watermark.png.
• Per-file config JSON artifacts are removed from dist/data/config (single runtime config contract).
• scripts/bootstrap_build.py uses system npm when available; otherwise it downloads a local portable Node.js/npm toolchain under .tools/node.
• scripts/bootstrap_build.py installs npm dependencies before running the build (npm ci when possible, fallback to npm install).
• scripts/bootstrap_build.py validates that every required runtime package from scripts/build-config.json is declared in package.json and installed before running npm run build.
• With --run-dev, the script checks whether Dockerfile.dev already runs npm run build; if yes, it skips local pre-build and lets Docker handle it.

Docker Image

The Docker image now uses the build pipeline (npm run build) and serves the generated dist/ output from nginx.

1. Start the container:

   docker compose -f compose.dev.yml up --build -d

2. Open the app in a browser: http://localhost:8080
3. Stop the container:

   docker compose -f compose.dev.yml down

Notes:

• The image build stage runs npm run build to generate cache-busted assets.
• The runtime nginx container serves only the built static files from dist/.

Attribution

• AI tools were used during development; all architectural decisions and system design choices are authored by the project owner.
• The commit history has been collapsed into a single commit to remove images and material that do not belong to the author.

License Summary

This repository uses a custom source-available license defined in LICENSE.md. The code is provided for educational and portfolio review only, and it is not open source. Commercial use of the software is explicitly and exclusively granted to Miagati. All other commercial usage, redistribution, derivative works, or deployment are prohibited unless explicitly authorized by the author.