# AdVajra

> AdVajra is a modern WordPress ad management and monetization command center. It provides publishers with a React-powered dashboard to create, place, target, track, rotate, protect, and optimize ads using a high-performance database and runtime architecture.

---

## 1. Technical Architecture

AdVajra is built with a decoupled architecture separating the admin CRUD interface, background tracking aggregation, and frontend delivery runtime.

### 1.1 Custom Database Infrastructure
Instead of bloating default WordPress options and meta tables, AdVajra isolates its operations in custom indexed tables for high-volume performance:
- `{$wpdb->prefix}advajra_placements`: Stores layout positions, page/paragraph configurations, and active assignments.
- `{$wpdb->prefix}advajra_activity_log`: Tracks all operational audits (ad/placement CRUD, module toggles, settings updates).
- `{$wpdb->prefix}advajra_stats` (Pro): Logs aggregated hourly/daily impressions, clicks, requests, and metrics per ad.

### 1.2 Modular Core (`ModuleManager`)
A centralized modular registration system dynamically activates or deactivates features:
- Core features like IP Blocker, Bot Protection, and Custom Code are registered dynamically.
- Pro upgrades replace free placeholder modules on the fly via standard filters, allowing a seamless swap without codebase duplication.

### 1.3 Optimized Render Pipeline
- **Snapshot Caching**: An runtime static registry (`AdSnapshotRepository`) primes and caches ad configurations, ensuring minimal database lookups during frontend rendering.
- **Suppression Heuristics**: Ad delivery bails early if a page context matches suppression settings, a user has a hidden role, or targeting rules fail.

---

## 2. Key Features

### 2.1 Ad Studio & Placements
- **Studios**: Support for standard Image banners, Rich Content layouts, and Plain/Code embeds. Alt text, dimension configurations, and device simulation are supported.
- **Placements**: 6 built-in position types (before content, after content, after paragraph, header, footer, shortcode). Supports manual placement via Gutenberg blocks, widgets, and shortcodes.
- **Frontend Preview**: Visual placement preview mode renders draft layouts on the live site layout without publishing.

### 2.2 Rotation & Targeting
- **Ad Groups**: Rotate multiple creatives inside a single placement slot. Supports random, weighted, or ordered rotation.
- **Recursive Targeting**: Target ads by post type, category, user role, and device. Evaluates rules recursively using nested `AND`/`OR` groups.

### 2.3 Smart Loading & Performance
- **Image Optimizations**: Ordinal-aware loading sets `loading="eager"` and `fetchpriority="high"` for above-the-fold creatives, and native lazy-loading for below-the-fold ads. All image ads receive `decoding="async"`.
- **Lazy Rendering**: Wraps ads in `<template>` tags and injects them only as they approach the viewport using `IntersectionObserver`.

### 2.4 Revenue Protection
- **Bot Protection**: Excludes spiders, crawlers, and headless browsers (Lighthouse, Puppeteer) from rendering ads.
- **IP Blocker**: Restricts ad delivery to specific blacklisted IP ranges.
- **Click Fraud Protection (CFP)**: Detects repeated clicks from identical visitor signatures, temporarily hiding targeted ads from bad actors and keeping analytics clean.
- **Ad Blocker Recovery**: Injects bait elements to detect active ad blockers, responding with custom modal alerts, content truncation, or custom page redirects.

### 2.5 Privacy & Consent
- **CMP Auto-Detection**: Integrates out-of-the-box with popular consent frameworks (Complianz, CookieYes, Cookiebot, Borlabs Cookie, Complianz-GDPR, ComplianZ, Complianz, Complianz, Real Cookie Banner, GDPR Cookie Compliance, WP Consent API).
- **Privacy-Safe Mode**: Disables tracking entirely and strips third-party pixels or beacons from frontend output if consent is denied.

### 2.6 Asynchronous Tracking Engine (Pro)
- **High Performance Ingest**: Frontend tracking (`tracking.js`) uses `navigator.sendBeacon` or `fetch` keepalives to batch events in the background.
- **Buffered Storage**: Events are written directly to high-speed memory buffers (APCu or Object Cache/Redis) or fallback files during web requests.
- **Cron Aggregator**: Background tasks pull buffered events and perform batch increment updates to the database on a custom cron interval, avoiding lock contention.

---

## 3. Developer Extensibility

AdVajra is fully extensible through WordPress actions and filters.

### 3.1 Key Filters
- `advajra_ad_output($html, $ad_id)`: Modify ad html before frontend output.
- `advajra_group_strategy($selected, $rotation, $pool, $group_id)`: Customize ad rotation algorithms.
- `advajra_ad_image_attributes($attrs, $snapshot)`: Modify smart loading image attributes.
- `advajra_should_track($bool, $type, $event)`: Programmatically override tracking consent rules.

### 3.2 Key Actions
- `advajra_ad_saved($ad_id, $request)`: Hook into ad configuration changes.
- `advajra_log($level, $message, $context)`: Dispatch custom entries to the debug logging system.

---

## 4. Navigation & Resources

- [Homepage](https://advajra.com) - Main website and product details.
- [Pricing](https://advajra.com/pricing) - Solo vs Agency plan comparison.
- [Support](https://advajra.com/support) - Help center and support contact form.
- [Blog](https://advajra.com/blog) - Optimization tips and monetization guides.
- [Sitemap](https://advajra.com/sitemap-index.xml) - Complete XML sitemap.