> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenarch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Joomla

> Joomla pay-per-crawl extension with AI bot detection — charge AI crawlers with USDC micropayments on Base. Full admin dashboard, non-custodial.

Full Joomla 5.x package with admin dashboard, bot detection, and payment gating.

## Requirements

* Joomla 5.0+
* PHP 8.1+
* MySQL 8.0+

## Installation

1. Download `pkg_xenarch.zip` from the [releases page](https://github.com/xenarch-ai/xenarch-plugins/releases)
2. Go to **System → Install Extensions** in your Joomla admin panel
3. Upload `pkg_xenarch.zip`

The installer creates the required database tables and configures HTTP headers automatically.

## What gets installed

The package contains three extensions:

| Extension                 | Type                | Purpose                        |
| ------------------------- | ------------------- | ------------------------------ |
| `com_xenarch`             | Component           | Admin dashboard + REST API     |
| `plg_system_xenarch`      | System Plugin       | Bot detection + payment gating |
| `plg_webservices_xenarch` | Web Services Plugin | API route registration         |

## Configuration

After installation, go to **Components → Xenarch** to open the dashboard.

### Onboarding flow

1. **Register** — create your publisher account
2. **Add site** — link your Joomla site to the Xenarch platform
3. **Set payout wallet** — enter your Base/Ethereum address for USDC payouts

### Settings

| Setting                | Default | Description                      |
| ---------------------- | ------- | -------------------------------- |
| `default_price`        | \$0.003 | Price per page in USD            |
| `gate_enabled`         | Yes     | Master toggle for payment gating |
| `gate_unknown_traffic` | Yes     | Gate non-browser traffic         |
| `payout_wallet`        | —       | Your Base address for payouts    |

### Bot category policies

Control how each type of AI traffic is handled:

```json theme={null}
{
  "ai_search": "allow",
  "ai_assistants": "charge",
  "ai_agents": "charge",
  "ai_training": "charge",
  "scrapers": "charge",
  "general_ai": "charge"
}
```

### Per-bot overrides

Override the category default for specific bots:

```json theme={null}
{
  "GPTBot": "allow",
  "ClaudeBot": "charge"
}
```

### Pricing rules

Set different prices for specific paths:

```json theme={null}
[
  { "path_contains": "/premium/", "price_usd": 0.01 },
  { "path_contains": "/research/", "price_usd": 0.005 }
]
```

## How it works

### Request flow

1. **Skip** — logged-in users, static assets, and `/.well-known/*` paths always pass through
2. **Check token** — if the request has a valid `Authorization: Bearer <token>`, allow it
3. **Detect bot** — match User-Agent against 100+ known AI bot signatures, then score headers
4. **Apply policy** — check per-bot override, then category default
5. **Respond** — allow (200), challenge (403 + browser proof), or gate (402 + payment payload)

### Discovery documents

The plugin automatically serves:

* **`/.well-known/pay.json`** — machine-readable pricing for AI agents
* **`/.well-known/xenarch.md`** — human-readable payment instructions

### Bot detection

Detection runs in priority order:

1. **Signature match** — 100+ known AI bot User-Agent strings
2. **Trusted search crawlers** — Googlebot, Bingbot, etc. (always allowed)
3. **HTTP client signatures** — python-requests, curl, wget, Go-http-client
4. **Browser proof cache** — valid proof cookie from a previous challenge
5. **Header scoring** — missing `Accept`, `Accept-Language`, `Sec-Fetch-*` headers increase suspicion score

## Build from source

```bash theme={null}
cd xenarch-plugins/joomla
./scripts/build-release.sh
# Output: src/packages/pkg_xenarch.zip
```

## Local development

```bash theme={null}
cd xenarch-plugins/joomla
docker compose up -d
# Joomla 5.4 + MySQL 8 at localhost:8889
```

Source files are mounted as volumes for live development.

## Admin UI development

The dashboard is a React + TypeScript app:

```bash theme={null}
cd xenarch-plugins/joomla/admin-ui
npm install
npm run build
```

Build output goes to `src/media/com_xenarch/js/` and `src/media/com_xenarch/css/`.