Ark — Unified Animal Data Ingestion & Mapping for WordPress

Ark is a modular, extensible WordPress plugin designed to ingest, normalise, and surface animal data from external providers (such as Pawlytics) into a WordPress environment. It provides a clean operational pipeline, a structured settings hub, and a modern dependency‑injected architecture.

Ark is built for organisations that need a reliable, auditable, and maintainable way to synchronise animal records into WordPress for public display, internal workflows, or downstream integrations.

---

✨ Key Features

• Provider‑agnostic ingestion pipeline
  Fetch, normalise, and process animal data from supported providers.

• Operational mapping layer
  Map external organisation identifiers to internal WordPress entities.

• Credentials management
  Secure, multi‑provider credential storage with inline editing.

• Settings Hub
  A unified, tabbed interface for all configuration.

• Diagnostics & Logs
  Built‑in telemetry and database‑backed logging.

• Extensible architecture
  New providers, pipelines, and settings pages can be added cleanly.

---

🧱 Architecture Overview

Ark is structured around a clear separation of concerns:

1. Dependency Injection Container

Ark uses a lightweight PSR‑11‑style container to construct and manage all services:

• Repositories
• Ingestion pipeline components
• Admin pages
• Settings sub‑pages
• Telemetry
• Provider factories

This ensures deterministic wiring and avoids hidden dependencies.

2. Admin Menu & Settings Hub

The WordPress admin interface is composed of:

• A top‑level Ark menu
• Operational pages (Dashboard, Animals, Ingestion, Diagnostics, Logs)
• A unified Settings Hub with tabs:
  • General
  • Provider
  • Credentials
  • Organisation Mapping
  • Advanced
  • License

Each tab is its own class, injected via the container.

3. Credentials System

Ark includes a secure credential store with:

• One row per provider
• Inline edit/delete
• Nonce‑protected actions
• Provider‑agnostic storage

The Credentials Manager is rendered directly inside the Settings Hub.

4. Ingestion Pipeline

The ingestion system is composed of:

• Fetcher — retrieves raw data from the provider
• Normalizer — converts provider‑specific fields into Ark’s internal schema
• Domain Service — applies operational rules
• Pipeline — orchestrates the full ingestion
• Ingestion Service — exposes a simple API for running ingestion
• Runner — coordinates ingestion for the active organisation

This modular design makes it easy to add new providers or extend behaviour.

5. Telemetry & Logging

Ark includes:

• A database‑backed logger
• Structured log entries
• A dedicated Logs page in the admin menu

This provides visibility into ingestion operations and system behaviour.

---

📁 Directory Structure

src/ Admin/ Pages/ # Admin pages & settings tabs Ark_Admin_Menu.php # Menu registration Core/ Container/ # DI container Auth/ # Credentials & provider auth Providers/ # Provider registry & factories Org/ # Organisation mapping & resolution Telemetry/ # Logging Database/ Schema.php # Core schema LogsSchema.php # Logging schema Ark_Installer.php # Activation installer Ingestion/ Animal/ Operational/ # Fetcher, normalizer, pipeline, services

---

🔌 Extending Ark

Ark is designed to be extended. You can:

• Add new providers
• Add new ingestion pipelines
• Add new settings tabs
• Add new admin pages
• Add new repositories

All extensions follow the same pattern:

1. Create the class
2. Register it in the DI container
3. Inject it where needed

The container ensures everything is wired cleanly.

---

🛠 Development

Requirements

• PHP 8.1+
• WordPress 6.0+
• Composer

Install dependencies

composer install

Activate the plugin

Upload or symlink the plugin directory into wp-content/plugins, then activate it in the WordPress admin.

Database installation

Ark automatically installs its schema on activation.

---

🤝 Contributing

Contributions are welcome!
Please open an issue or submit a pull request.

---

📄 License

MIT License.
See LICENSE for details.