# Project History

The mission of Baxxon is to provide a single, human-readable codebase that can be deployed seamlessly across web and mobile platforms without the weight of traditional enterprise frameworks.

---

## Architectural Evolution

### 1st Generation: The Monolithic PHP Era
*   **Design:** All requests were processed through a single index page via `php-mod` on Apache.
*   **Principle:** One application hosting many sites, each made of many pages. Configuration dictated specific content and functionality.

### 2nd Generation: PHP + jQuery (The Hybrid SPA)
*   **Design:** Moved away from full-page post-backs. The server delivered a payload of HTML data, which was then manipulated on the client via jQuery.
*   **Principle:** Asynchronous CRUD operations via AJAX, while maintaining a PHP/Apache backend.

### Exploratory Phase: Angular & Ionic
*   **Observation:** Investigated a progression to Angular and Ionic for mobile parity.
*   **Decision:** While Angular offered structure, the additional learning curve and the overhead of TypeScript compilation conflicted with the goal of "Baxxon Simplicity." This led to the decision to build a minimalist Node.js core instead.

### 3rd Generation: Node.js (The Modern Era)
*   **Design:** A complete rewrite using JavaScript ESM and a custom Node.js server.
*   **The Breakthrough:** This generation formalized the **"Visual Contract"** routing system:
    *   **Physical Assets:** URLs with dots (files).
    *   **Dynamic Logic (JS Modules):** URLs without dots (modules).
*   **TextDB:** Implementation of a flat-file database using folders as tables and text files as records.

---

## The AI-Assisted Era (v3.0+)

Starting with version 3.0, the development of Baxxon shifted to a collaborative "vibe" between the author and Large Language Models, enabling rapid refactoring and architectural hardening.

### v3.0 - v3.3: Foundation & Hardening
*   Initial code refactor with ChatGPT.
*   Hardened static site serving and the Template class.
*   Fixed configuration patterns for vhosts and environment variables.

### v3.5 - v3.7: SPA & Resiliency
*   **API:** Added status tracking, retry attempts, and network dropout handling.
*   **TextDB:** Added automatic `dateCreated` and `dateModified` timestamps.
*   **UI:** Implemented type-aware sorting, pagination, and dynamic table rendering.
*   **Resiliency:** Developed "Optimistic UI" for SPAs, allowing CRUD operations to function during network failures via a localStorage-backed action queue.

### v3.8: The Specification & Configuration Refinement
*   **Convention over Configuration**: Removed the static `config.js` requirement. The framework now automatically loads overrides from the application's `package.json` under the `"baxxon"` key, enabling a cleaner "install and run" experience.
*   **Environment Branding**: Standardized the environment variable prefix to `BAXXON_` (e.g., `BAXXON_HOST`, `BAXXON_PORT_HTTP`) for better brand consistency and collision avoidance.
*   **Routing Refinement**: Implemented **Boolean Flags** (unpaired segments default to '1') for cleaner logic in modules.
*   **The List Tool**: Exposed `bx.params` as a raw array for positional, index-based routing.
*   **Property Standardization**: Renamed `bx.docroot` to `bx.paths.site` and exposed the hierarchical `bx.paths` object (app, site, stat, mod) for better transparency and path management.
*   **Dependency Audit**: Fixed a `ReferenceError` by importing the missing `querystring` module for form POST handling.

### v3.8.3: CLI Expansion & Logger Hardening
*   **Example Loader**: Enhanced the Baxxon CLI with a `load` command (`baxxon load <type>`), allowing users to easily swap the `_default` site between `static`, `dynamic`, and `spa` examples.
*   **Interactive Examples**: Refactored all three example sites to provide contextual demonstrations of core features. The **Dynamic Example** now includes a "Slash-Param Playground" and an enhanced API demonstration that shows raw JSON responses in a dedicated viewer.
*   **Logger Reliability**: Fixed a missing `path` import in `logger.js` and added version caching, ensuring the startup banner always displays the correct framework version.
*   **Visual Logging Blocks**: Refined the request logger to use a "Lazy Separator" approach for cleaner grouped console output.
*   **Robust Logging**: Updated the `save()` method to safely handle `null` arguments and return the formatted message for better downstream utility.

### v3.8.2: Onboarding & Brand Refinement
*   **Interactive Setup**: Added a `postinstall` script and CLI utility (`baxxon init`) that queries the user to automatically create the `sites/_default` structure and a "Hello World" example upon installation.
*   **Terminology Shift**: Standardized all documentation and examples to use "Dynamic Logic (JS Modules)" to reduce onboarding friction and emphasize "No Magic."
*   **Brand Cleanup**: Migrated all legacy "Baax" references to "Baxxon" across documentation and examples.
*   **Example Inclusion**: Added core example projects (`static`, `dynamic`, `spa`) directly to the repository for better distribution.

### v3.8.1: Pathing & Vhost Fixes
*   **Initialization Order**: Moved `setPaths()` after `host` and `reqURL` initialization to ensure site paths are correctly derived from the request.
*   **Vhost Matching**: Fixed a regex bug in vhost validation by properly escaping dots in domain names.
*   **Stability**: Removed redundant `cacheWrite` during HTML rendering to prevent potential file-system collisions during concurrent requests.
*   **Distribution**: Added `files` manifest to `package.json` to ensure a clean, lightweight NPM package.

### v3.9.0: Documentation & UI Modernization
*   **The 6+1 Refinement Model**: Established a disciplined abstraction hierarchy: One-liner -> Philosophy -> Features -> README -> Blueprint Docs -> Source Code + History Narrative.
*   **Documentation Hardening**: Rewrote `docs.md` to be a 1:1 technical blueprint of the framework.
*   **Axios-Inspired UX**: Refined the `baxxon.ca` interface with a glassmorphism header, minimalist navigation, and professional charcoal-themed code blocks.
*   **Smart Code Interactions**: Implemented a universal JavaScript utility for code blocks that provides automatic language labeling and a "smart" copy-to-clipboard button.

### v3.10.0: Tutorial Baseline & Error Handling Precision
*   **Standalone Tutorial Strategy**: Pivoted the example library to focus exclusively on standalone execution. Removed portal-specific "export" logic to ensure examples remain intuitive, representative, and serve as production-ready templates.
*   **Standardized Example Architecture**: Re-aligned `example-1-static`, `example-2-dynamic`, and `example-3-api` with a consistent content structure (Title, Subtitle, Intro, Demo) and a premium visual style.
*   **Resilient API Client**: Refactored the client-side `API` utility into a production-grade requester featuring exponential backoff, robust JSON parsing guards, and standardized error responses for network, parse, and HTTP failures.
*   **Deterministic Error Fix**: Corrected a logic bug in `render.FILE` to ensure the **Visual Contract** is honored. Unsupported file types (e.g., `.php`) now correctly return a **415 error** even if the physical file is missing, prioritizing type safety over existence checks.
*   **API Expansion**: Added `bx.version()` to the Controller API, allowing modules to programmatically access the current framework version via the project's `package.json`.
*   **UX Refinement**: Implemented a scroll-based background fade on the main portal, enhancing the "premium" aesthetic with subtle watermark-style branding.

### v3.11.0: Architectural Integrity & API Synchronization
*   **The Blueprint Sync**: Conducted a comprehensive audit of Layer 5 (Docs) and Layer 6 (Source) to ensure 1:1 alignment. This hardened the **6+1 Refinement Pattern** by identifying and fixing several documentation gaps and source inconsistencies.
*   **TextDB Semantic Alignment**: Renamed the `blob` parameter to `body` across all TextDB methods (`addRecord`, `updateRecord`, `parseFile`). This aligns the internal implementation with the public documentation and improves conceptual clarity for developers.
*   **API Expansion & Documentation**: Added the missing `bx.render.TEXT` method and previously undocumented `bx.paths` properties (`doc`, `app`) to the technical blueprint.
*   **Template Engine Enhancements**: Exposed the `pushVars(vars)` batch method in the documentation, allowing for efficient multi-variable appends to placeholders.
*   **CLI Robustness**: Fixed a command mismatch in the documentation, ensuring `baxxon load api` is correctly referenced instead of the legacy "interaction" type.
*   **JSON Safety**: Documented the object-root requirement for `bx.render.JSON` to reflect the framework's strict validation logic.

### v3.11.1: Backup Logic & API Responder Synchronization
*   **Deterministic Backup Paths**: Fixed a logic bug in the SPA responder where data backups were being saved to the framework root instead of the site root. Forcing `bx.paths.site` as the base directory ensures backups remain contained within the current site's structure.
*   **Responder API Sync**: Synchronized the SPA responder with the v3.11.0 TextDB refactor. Updated record metadata extraction to use `_body` instead of the legacy `_blob` property, ensuring full compatibility between the API logic and the data engine.

### v3.11.4: Service Transparency & UI Integration
*   **Background Service Visibility**: Integrated a visual status indicator for the universal `Service` utility. Users can now monitor active background tasks (like the Backup Service and Network Check) directly in the SPA interface.
*   **Viewer Expansion**: Added a `buildServices` component to the `Viewer` class, providing a real-time "heartbeat" display for registered services, including run status and last execution timestamps.
*   **Flexible Layouts**: Enhanced the `listTemplate` to support a `{services}` placeholder, allowing for deterministic placement of service monitors within the application layout.

### v3.11.5: Style Isolation & CSS Refactoring
*   **External Style Migration**: Refactored the SPA framework to remove all inline CSS from the JavaScript Controller and Viewer components. All styling is now centrally managed via a new external stylesheet at `public/styles/spa.css`, improving maintainability and separation of concerns.
*   **Dynamic Component Styling**: Standardized class-based styling for complex UI components, including the new Service Heartbeat monitors, Backup controls, and Pagination units.
*   **Template Integration**: Updated the site templates to link the isolated SPA stylesheet, ensuring a consistent visual experience while keeping the JavaScript logic "clean" and focused on state and behavior.

### v3.11.6: Developer Experience & Automated State
*   **Auto-Reset Initialization**: Transitioned the "Reset Test Data" utility from a manual button click to an automated lifecycle event. The framework now ensures a clean data state on every page load for the SPA example, streamlining the development and testing loop.
*   **UI Streamlining**: Removed redundant reset controls from the example layouts and updated the visual context to reflect the automated data management strategy.

### v3.11.7: Path Interpolation Stability
*   **Reset Engine Hardening**: Resolved a critical pathing bug in the developer "Reset Data" utility where literal template strings were being passed to the filesystem engine. Forcing server-side path resolution via `bx.paths.site` ensures the automated reset lifecycle is robust and deterministic.

### v3.11.8: Deterministic Connectivity Monitoring
*   **Global Status Indicator**: Implemented a global network connectivity monitor that provides clear visual feedback when the application is in "Offline Mode."
*   **Contextual Visibility**: Optimized the status UI to remain hidden during normal operation, only appearing as a prominent amber badge when server connectivity is lost, ensuring a clean interface without sacrificing transparency.
*   **Event-Driven UI Refresh**: Enhanced the Controller to trigger immediate UI re-renders upon connectivity state transitions, ensuring the connectivity status and background services remain perfectly synchronized with the underlying network state.

### v3.11.9: Hybrid Service Control & Manual Triggers
*   **Manual Task Invocation**: Enhanced the universal `Service` utility with a `run()` method, allowing background tasks to be triggered manually without waiting for their automated timers.
*   **Interactive Service UI**: Updated the SPA Viewer to render "Run Now" buttons for services configured with `allowManual: true`. This provides developers and users with direct control over tasks like backups and network heartbeats.
*   **Recursive Timer Logic**: Implemented deterministic timer resetting upon manual execution. Triggering a service manually now restarts its interval, preventing redundant executions and ensuring a stable automated rhythm.

### v3.11.10: Service Consolidation & Transparent Sync
*   **Unified Background Monitor**: Consolidated the disparate Backup and Network components into a single, comprehensive "Services" UI. This reduces interface clutter while providing a centralized view of all automated framework tasks.
*   **Data Sync Visibility**: Formalized the offline-to-online synchronization process as a first-class "Data Sync" service. Users now receive real-time feedback on "Pending Changes" and successful server pushes.
*   **Custom Status Messaging**: Enhanced the `Service` utility to support rich, context-aware status messages. Services can now report detailed information (e.g., "Last Success: 2:30 PM") instead of simple execution timestamps.
*   **Architectural Stability**: Resolved a JavaScript parse regression caused by nested brace errors in the Viewer class, restoring full rendering stability to the SPA example.

### v3.12.0: Dedicated State Management & Local Persistence
*   **Deterministic Operating Modes**: Refactored the SPA architecture to support explicit "Local" and "Network" modes. Users can now choose their operating state, with the system providing automatic failover to Local mode upon API failure.
*   **Persistent LocalStorage DB**: Enhanced the Model to utilize `localStorage` as a primary, persistent data store when operating offline. Records now survive page reloads during network outages, with automatic synchronization occurring upon reconnection.
*   **API Resilience Interceptors**: Modified the `API` client to broadcast global `api-failure` events. This allows the Controller to instantly detect server drops and transition the UI state without waiting for background heartbeats.
*   **Framework-Level HEAD Support**: Upgraded the core Baxxon request handler to support `HEAD` requests, enabling high-frequency connectivity probes that verify server availability without data overhead.

### v3.12.1: Performance & Recovery Optimization
*   **Heartbeat Calibration**: Optimized the "Network Check" service frequency to 60 seconds. This reduces background network chatter while preserving the SPA's deterministic auto-recovery capabilities.
*   **Resilient Probing**: Leveraged the new framework-level `HEAD` support to ensure background connectivity probes are as lightweight and non-intrusive as possible.

### v3.12.3: CLI Workflow & Explicit Initialization
*   **Deterministic Onboarding**: Removed the `postinstall` auto-initialization script. Project initialization is now strictly explicit via `npx baxxon init`, preventing unintended scaffolding during CI/CD or background dependency installations.
*   **VHost CLI Integration**: Promoted the `add` command, allowing developers to scaffold new site directories and register domain mappings in `package.json` simultaneously.
*   **Flexible Templating**: Expanded the `load` command to accept optional destination parameters, enabling templates to be injected directly into custom virtual host directories.
*   **Safe NPM Execution**: The initialization script now natively maps execution to a dedicated `"baxxon"` script in `package.json`. This prevents destructive conflicts with user-defined `"start"` scripts (e.g., `nodemon` or `pm2`) while maintaining a predictable execution standard (`npm run baxxon`).

### v3.12.2: Interactive Mode Control & UI Polish
*   **Tactile Mode Switching**: Refactored the "Operating Mode" selector from a static dropdown into a modern, interactive toggle switch. This provides a clearer mental model for "Network" vs. "Local" operation.
*   **Accessible Switch UI**: Implemented a custom CSS slider for the mode toggle, featuring smooth transitions, state-aware coloring (Green for Network), and consistent labeling for improved accessibility.
*   **State-Driven Visualization**: Synchronized the toggle state with the active operating mode, ensuring the UI remains deterministic even during automatic failover scenarios.








