Architecture

System Overview

The plugin operates as part of a three-tier architecture:

RecMan (app.recman.no)
        |
        v
Bonsy API (recman-api.bonsy.no)   ← enriches, translates, caches, validates
        |
        v
WordPress Plugin (your site)       ← caches locally, renders on frontend
        |
        v
Your Visitors                      ← see the jobs

The plugin never talks directly to RecMan. All communication goes through the Bonsy API middleware.

Bonsy API (Middleware)

The Bonsy API acts as an intelligent layer between RecMan and your site:

• Fetches and normalizes data from the RecMan API
• Cleans HTML — sanitizes job descriptions for proper rendering
• Generates excerpts — ~200 character previews with sentence-boundary detection
• Translates field values — sector, employment type, location, etc.
• Creates permalinks — URL-friendly slugs from job titles
• Formats apply URLs — direct links to the application form
• Normalizes social links — ensures HTTPS for Facebook, LinkedIn, Twitter, Instagram
• Calculates similar jobs — weighted matching across 14 fields
• Generates search indexes — lowercased, compressed strings for client-side search
• Validates licenses — checks API key permissions and license expiration
• Handles sorting — by post ID, updated date, or start date
• Manages expired jobs — configurable retention of recently expired postings

API Caching

The Bonsy API maintains a 5-minute server-side cache per client. Both processed and raw JSON are cached. Cache can be flushed with ?flush=1.

WordPress Plugin

The plugin handles the client-side:

Smart Local Caching

File-based JSON cache in wp-content/cache/bonsy-recman/ with time-of-day aware refresh intervals. Falls back to cached data if the API is unreachable.

Display Layer

Two approaches for rendering jobs:

1. Shortcodes — drop into any page, customizable HTML/CSS from admin
2. Template functions — PHP API following WordPress conventions

SEO Module

Generates page titles, canonical URLs, meta descriptions, Open Graph tags, and Twitter Cards. Aware of Yoast SEO and The SEO Framework.

URL Rewriting

Creates clean URLs for individual job posts and handles expired job redirects.

Admin Interface

Tabbed dashboard for managing settings, viewing cache, editing templates, and monitoring jobs.

Plugin Code Structure

The plugin follows a single-responsibility class architecture:

Class	Responsibility
Recman_Api_Client	API communication
Recman_Cache_Manager	Local caching
Recman_Job_Filter	Filtering logic
Recman_Job_Repository	Data access
Recman_Job_Iterator	Loop/iteration
Recman_Seo	SEO metadata
Recman_Rewrite	URL rewriting
Recman_Post	Custom Post Type

Security

• WordPress nonces on all admin actions
• Capability checks on admin pages
• Input sanitization and output escaping throughout
• RecMan API key stored on Bonsy server, not in WordPress
• Timing-safe comparison for cache flush authentication
• Secret key authentication for CPT cron endpoint

Technical Requirements

Component	Requirement
WordPress	6.4.1+
PHP	8.0+
Dependencies	None (zero JS or PHP dependencies)