[![Baxxon Logo](https://baxxon.ca/logo-baxxon.svg)](https://baxxon.ca/)

**A structural web framework for Node.js.**

Baxxon leverages standard Node.js APIs and ES Modules to provide a transparent foundation for web applications. By eliminating hidden logic and complex abstractions, Baxxon ensures your code remains portable, predictable, and fast.

## The Baxxon Philosophy: The Visual Contract

Baxxon eliminates routing ambiguity by splitting the web into two mutually exclusive categories based on the URL structure. This "Visual Contract" ensures that developers and browsers alike know exactly how a request will be handled:

*   **Physical Assets (Static):** Any URL containing a file extension (a dot, e.g., `/style.css`) is strictly served from the `public/` directory.
*   **Dynamic Logic (JS Modules):** Any URL without a dot (e.g., `/api/user`) is treated as a logic request and routed to the `modules/` directory. These are standard ES modules exporting a default handler function.

---

## Core Features

### Routing simplified
Baxxon implements a deterministic router that removes the need for centralized routing tables. By following the Visual Contract, your directory structure *is* your routing map.

### URL as data structure
The integrated **Slash-Param Engine** treats the URL as a data structure. Any trailing segments following a module path are automatically parsed into the `bx.params` array and the standard `bx.reqURL.searchParams` object for instant use.

### Markdown by default
Build content-rich sites with zero extra setup. Baxxon natively detects, parses, and renders Markdown files via the integrated `marked` engine.

### Multiple sites, one install
Scale your infrastructure using Baxxon's built-in **Virtual Hosting** engine. Manage multiple independent domains and sites from a single installation by mapping hostnames to subdirectories in your `sites/` folder.

### Consistent API logic
Pages and APIs share a unified paradigm. In Baxxon, an API is simply a JS module that returns JSON. The framework handles the boilerplate, including automatic body parsing for JSON and URL-encoded form data.

### Files as database
Baxxon uses **TextDB**, a filesystem-native database where folders act as tables and `.txt` files act as records. Data is stored in a human-readable Header:Value format, making your database searchable via standard system tools and perfectly suited for version control.

---

## Example Library

Baxxon includes a collection of standalone example sites that serve as both tutorials and production-ready templates. You can load these into your `sites/_default` directory using the Baxxon CLI.

### 1. Static Content (`example-1-static`)
*   **Focus:** Zero-config baseline and the **Visual Contract** for physical assets.
*   **Architecture:** 100% Static. Served directly from the `public/` folder.
*   **Demonstration:** Shows how Baxxon uses the presence of a "dot" in the URL to bypass the logic engine and serve high-performance static assets with automatic MIME type handling and deterministic error responses (404/415).

### 2. Dynamic Content (`example-2-dynamic`)
*   **Focus:** Server-side logic, URL parsing, and the native Template Engine.
*   **Architecture:** JS Module driven (`modules/index.js`).
*   **Demonstration:** Showcases the **Slash-Param Engine** (converting trailing URL segments into data), the variety of native **Render Methods** (HTML, Markdown, JSON, etc.), and the performance of the `{placeholder}` based template system.

### 3. Dynamic API (`example-3-api`)
*   **Focus:** Client-server interaction and **Network Resiliency**.
*   **Architecture:** Hybrid (JS Module Page + Dedicated API Responder).
*   **Demonstration:** Demonstrates how pages and APIs share the same directory structure and logic. It highlights the refactored **Resilient API** utility, featuring built-in exponential backoff, robust error handling, and connectivity tracking.

### 4. SPA Architecture (`example-4-spa`)
*   **Focus:** Advanced Single Page Application (SPA) architecture and **TextDB** transparency.
*   **Architecture:** Complex JS Module system coordinating a client-side Controller (`spa.js`) with server-side API responders.
*   **Demonstration:** Features deterministic **Dual-Mode Operation (Local/Network)** backed by persistent `localStorage`, the integrated **TextDB Engine**, and a unified background service monitor for automatic data synchronization and backups.

### Shared Tools
*   **`bx.log`**: A unified logger for `note`, `warn`, and `error` terminal feedback.
*   **`bx.templates`**: A recursive engine for merging data into reusable HTML structures.
*   **`bx.renderContent(file, vars)`**: Injects fragments into layouts with optional variable replacement.

---

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/).

Before installing, [download and install Node.js](https://nodejs.org/en/download/).

```bash
mkdir {my-baxxon-project}
cd {my-baxxon-project}
npm install baxxon
```

### Quick Start
To start a new Baxxon project, you must explicitly run the initialization command after installing the package. This will configure your project and scaffold the default site structure.

```bash
npx baxxon init
```

Baxxon will set up the following structure for you:

```bash
{my-baxxon-project}/
|
|---package.json
|---node_modules/
|
|---sites/
    |---_default/
        |---modules/
        |---public/
            |---css/
```

### Manual Setup & Examples

You can use the Baxxon CLI to add virtual hosts or load examples into your project.

#### Add Virtual Host
Scaffolds a new directory and registers the domain in your configuration.
```bash
npx baxxon add <domain> [dir]
```

#### Load Example
Loads a template into a specified directory (defaults to `_default`).
```bash
npx baxxon load static [dest]
npm run baxxon
```

#### Available Example Types:

---

## Configuration

Baxxon uses "Convention over Configuration". Default values can be overridden in your project's `package.json` file under the `"baxxon"` key:

```json
{
  "name": "my-app",
  "baxxon": {
    "server": {
      "portHttp": 8080
    },
    "vhosts": {
      "domainDirs": {
        "example.com": "example-site"
      }
    }
  }
}
```

---

## Docs

    * [Website](https://baxxon.ca/)
    * [GitHub](https://github.com/lornetaylor/baxxon)

## Security Issues

If you discover a security vulnerability in Baxxon, please report it via the GitHub repository.

## Author

The original author of Baxxon is [Lorne Taylor](https://github.com/lornetaylor)

## License

  [MIT](LICENSE)
