Design multi-target architecture (P-008)

[Puttrix]

Overview

Design and implement multi-target support to enable Trafficinator to generate load against multiple Matomo instances simultaneously with independent configuration per target.

Problem Statement

Currently, Trafficinator can only target a single Matomo instance at a time. Users who manage multiple Matomo deployments (e.g., dev/staging/prod environments, different clients, regional instances) must run separate containers with different configurations.

Proposed Solution

Enable multi-target configuration where users can define multiple Matomo endpoints with:

• Independent authentication tokens
• Per-target visit weights/distribution
• Per-target daily caps
• Shared or per-target URL/event/funnel configs

Acceptance Criteria

Backend/Config Model

• Extend Pydantic models to support array of target configs
• Validate per-target settings (URL, site_id, token_auth, weight)
• Support shared global defaults with per-target overrides
• Migrate single-target presets to multi-target schema
• Database schema supports storing multi-target configs

Loader Implementation

• Distribute visits across targets based on weights
• Honor per-target daily caps
• Support per-target timezone/currency overrides
• Maintain existing single-target compatibility
• Handle per-target connectivity failures gracefully

API/Control UI

• New /api/targets CRUD endpoints for managing targets
• Multi-target config form in UI (add/edit/remove targets)
• Status dashboard shows per-target metrics
• Presets can save/load multi-target configs
• Validation checks all target URLs before start

Testing & Documentation

• Unit tests for target distribution logic
• Integration tests with multiple mock targets
• Pytest coverage for weight/cap enforcement
• Update WEB_UI_GUIDE with multi-target usage
• Migration guide for existing single-target deployments
• ADR documenting architecture decisions

Open Design Questions

1. Config structure: Array of targets vs. nested object with target IDs?
2. Weight distribution: Percentage-based or ratio-based?
3. Shared vs. per-target: Should URLs/events/funnels be global or per-target?
4. Backward compatibility: Auto-migrate existing single-target configs or require manual conversion?
5. Status reporting: How to surface per-target success rates and errors in UI?

Example Use Cases

Use Case 1: Multi-Environment Testing

targets:
  - name: "Development"
    url: "https://dev.analytics.example.com/matomo.php"
    site_id: 1
    weight: 20
    visits_per_day: 1000
  - name: "Staging"
    url: "https://staging.analytics.example.com/matomo.php"
    site_id: 1
    weight: 30
    visits_per_day: 5000
  - name: "Production"
    url: "https://analytics.example.com/matomo.php"
    site_id: 1
    weight: 50
    visits_per_day: 20000

Use Case 2: Multi-Client Load Generation

targets:
  - name: "Client A"
    url: "https://client-a.matomocloud.com/matomo.php"
    site_id: 1
    token_auth: "xxx"
    timezone: "America/New_York"
    visits_per_day: 10000
  - name: "Client B"
    url: "https://client-b.matomocloud.com/matomo.php"
    site_id: 2
    token_auth: "yyy"
    timezone: "Europe/London"
    visits_per_day: 15000

Related Items

• Depends on: None (can be implemented independently)
• Blocks: P-009 (advanced reporting could show per-target metrics)
• Related to: P-006 (journey realism works with multi-target)

Estimated Effort

8 hours (as per backlog P-008)

• Config/models: 2h
• Loader logic: 3h
• UI/API: 2h
• Testing/docs: 1h

Priority

Medium - Nice to have but not blocking current features. Useful for larger deployments and testing scenarios.

Labels

enhancement, planning, architecture, p-008