> For the complete documentation index, see [llms.txt](https://hollow-peak.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hollow-peak.gitbook.io/docs/technical-reference/architecture-notes.md).

# Architecture Notes

How the platform is put together, for developers.

A conventional Laravel 11 application. Nothing here requires unusual knowledge.

## Layout

```
app/
├── Http/Controllers/    Dashboard, Store, Customer, public
├── Models/              Eloquent models, grouped by domain
├── Services/            Business logic
├── Payments/            Gateway interface and implementations
├── Support/             Registries and helpers
└── Console/Commands/    The installer
```

## Registries

Three registries drive most of the extensible behaviour. Each is a single source of truth read by several parts of the application.

### `App\Support\Modules`

Defines the 23 switchable features. Drives the sidebar, route availability and block visibility.

### `App\Support\PageBlocks`

Defines every page-builder block — label, group, icon, fields, and which module it needs.

Adding a block means adding a definition here and creating `resources/views/blocks/your-block.blade.php`. The registry then drives the palette, the inspector and the sanitiser without further work.

### `App\Payments\PaymentRouter`

Maps payment methods to providers. Adding a provider means implementing `PaymentGateway` and registering it here.

## Settings

`App\Services\SettingsService` holds configuration in the database with defaults in code.

* `SettingsService::defaults()` is the authoritative list
* `site('key', $fallback)` reads one anywhere
* Keys matching the secret patterns — `*.api_key`, `*.secret`, `*.secured_key`, `*.webhook_secret`, `*.password`, `*.private_key`, `*.access_token` — are **encrypted at rest**
* A blank submission for a secret means “unchanged”, never “clear it”
* Every write is versioned, with secrets redacted in the history

{% hint style="info" %}
If you add a credential setting, name it so it matches a secret pattern. A provider using an unfamiliar word for “secret” is how a credential ends up stored in the clear.
{% endhint %}

## Permissions

`User::can()` is overridden to check role permissions directly rather than using Gates or Policies. Use `auth()->user()?->can('slug')` in controllers and views.

The owner role short-circuits to true.

## Money

All amounts are **integer minor units** — 2500 means 25.00 in a two-decimal currency. `App\Support\Money` converts for display and input.

Never store money as a float.

## Front-end

Most of the interface is plain CSS and JavaScript in `public/css` and `public/js`, with no build step — which is why installing needs no Node.

Vite handles only `resources/js/portfolio-viewer.js` (Three.js) and `resources/js/portfolio-code.js` (highlight.js), both loaded on demand.

Assets are versioned by `asset_v()`, which appends the file's modification time.

## The page editor

Two halves talking by `postMessage`:

* `public/js/page-builder.js` — the editor shell, holding the document
* `public/js/page-canvas.js` — inside the iframe, handling selection, in-place editing and drag targets

The document lives in the parent; the canvas reports changes upward and receives fresh HTML back. One copy of the truth.

{% hint style="warning" %}
Blocks are swapped into the canvas as markup after load, which is too late for a stylesheet pushed by a Blade `@push`. Any stylesheet a block needs must also be linked in `resources/views/dashboard/site/pages/canvas.blade.php`, or the block is styled on reload and bare the moment it is dragged in.
{% endhint %}

## Tests

```bash
php artisan test
```

329 tests on an in-memory SQLite database. They do not touch your development data.

Worth knowing about `ViewsCompileTest`: it compiles every Blade view and checks the result parses. Blade fails quietly when it declines to compile a directive — leaving an orphan `endif` and a 500 that appears only when somebody opens that page. This test catches the whole class.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://hollow-peak.gitbook.io/docs/technical-reference/architecture-notes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
