Architecture Specifications

The 16 architecture blueprints define what each structural component of a Weblisk deployment is, what it's responsible for, and how it interacts with everything else. These are the building blocks — protocol says how things talk, architecture says what the things are.

Architecture blueprints don't prescribe implementation details — they define responsibilities, interfaces, and constraints. A conforming orchestrator in Go and one in Rust must behave identically from the outside, even though their internals differ completely.

Orchestrator

The orchestrator is the trust anchor of every deployment. It doesn't execute business logic — it manages identity, registration, routing, discovery, and the audit trail. Every agent registers with the orchestrator. Every task routes through it. Every capability grant originates from it.

Responsibilities

• Agent registration: Verify Ed25519 signatures, issue WLT tokens, assign agent IDs
• Service directory: Maintain the live registry of all agents — names, URLs, capabilities, health status
• Task routing: Accept task submissions and forward to the target agent (directly or via domain controller)
• Channel brokering: Create time-limited channels for direct agent-to-agent communication
• Namespace management: Enforce unique naming across agents, prevent collisions
• Audit logging: Record every operation in an append-only log — registrations, tasks, messages, approvals
• Strategy management: Store business strategies and observations for the lifecycle loop

Endpoints

What It Does NOT Do

• Does NOT execute agent logic — it routes, doesn't compute
• Does NOT store business data — agents own their data
• Does NOT make decisions — it enforces policies declared elsewhere
• Does NOT communicate externally — only agents talk to the outside world

Domain Controller

Domain controllers are business logic directors. They don't do the work themselves — they decompose complex requests into multi-agent workflows, coordinate execution order, handle failure cases, and aggregate results.

Responsibilities

• Workflow declaration: Define multi-step workflows as directed acyclic graphs (DAGs)
• Task decomposition: Break incoming requests into sub-tasks for specialist agents
• Coordination: Manage execution order, parallel branches, conditional paths, and join points
• Failure handling: Retry transient failures, circuit-break on persistent failures, report partial results
• Result aggregation: Combine outputs from multiple agents into a unified response
• Event-driven triggering: React to observations, scheduled events, or external triggers

Domain vs. Agent

Workflow Definition

workflows:
  full-audit:
    trigger: manual
    steps:
      - id: analyze
        agent: seo-analyzer
        inputs: { html_files: "$input.files" }
      - id: check-a11y
        agent: a11y-checker
        inputs: { html_files: "$input.files" }
        parallel: true         # Runs alongside 'analyze'
      - id: generate-fixes
        agent: seo-writer
        depends_on: [analyze, check-a11y]
        inputs:
          seo_report: "$steps.analyze.output"
          a11y_report: "$steps.check-a11y.output"
      - id: approve
        type: approval_gate
        depends_on: [generate-fixes]

Agent Base

The agent base blueprint defines the minimal contract every agent must satisfy — 5 standard endpoints, capability declaration, pub/sub integration, and operational behaviour (retry, circuit breaker, health reporting).

Required Endpoints

Agent Types

• Work agent (type: "agent") — domain-specific executor. Does the actual computation.
• Domain controller (type: "domain") — workflow coordinator. Decomposes and routes.
• Infrastructure agent (type: "infrastructure") — system service. Always running, hub-scoped.

Operational Behaviour

• Registration: On startup, build manifest, sign it, POST to orchestrator, store the returned token
• Health reporting: Respond to GET /v1/health within 1 second; include uptime, version, and queue depth
• Concurrency: Respect max_concurrent from manifest — reject excess with 429
• Graceful shutdown: Complete in-flight tasks, deregister from orchestrator, then exit
• Service directory: Accept pushes from orchestrator; use for agent-to-agent messaging lookups

Application Gateway

The application gateway is the end-user edge — it sits between external clients (browsers, mobile apps, third-party services) and the internal agent network. It handles authentication, authorization, rate limiting, and request mediation.

Responsibilities

• Session management: Create and validate user sessions (implements auth-session or auth-token patterns)
• ABAC enforcement: Attribute-Based Access Control — evaluate policies against user attributes, resource attributes, and context
• Rate limiting: Per-user, per-IP, per-endpoint rate limits with configurable windows
• Route protection: Map external routes to internal agents; block undeclared routes
• Request mediation: Transform external request format → internal TaskRequest; transform TaskResult → external response
• CORS management: Enforce origin allowlists per route

Request Flow

Client request
  → Rate limiter (429 if exceeded)
  → Authentication (401 if invalid)
  → ABAC policy evaluation (403 if denied)
  → Route resolution (404 if unmapped)
  → Request mediation (transform to TaskRequest)
  → Orchestrator /v1/task submission
  → Agent execution
  → Response mediation (transform from TaskResult)
  → Client response

Admin Gateway

The admin gateway is a completely separate entry point for platform operators. It runs on a different port (or network), uses different authentication, and enforces stricter controls than the application gateway.

Security Model

• Separate network: MUST NOT share an ingress path with the application gateway
• Ed25519 operator identity: Operators authenticate with their own Ed25519 keypair — not passwords
• MFA required: Second factor verification for all state-changing operations
• IP allowlist: Only whitelisted IP ranges can reach the admin gateway
• 4-eyes approval: Destructive operations (agent removal, policy changes, data deletion) require approval from a second operator
• Role-based access: Operators have explicit roles — viewer, operator, admin, superadmin

Admin Operations

Client Architecture

The client blueprint defines how external consumers (browsers, mobile apps, CLI tools, third-party services) interact with the platform — what they can see, what they can do, and what data boundaries apply.

Client Taxonomy

Data Boundary Rules

• Clients NEVER interact directly with agents — all traffic routes through the application gateway
• Response payloads are filtered by the gateway based on client trust level and requested scope
• Internal fields (agent IDs, trace IDs, raw task results) are stripped before client delivery
• File access is proxied — clients receive signed URLs with expiry, never direct storage paths

Hub

The hub blueprint defines how a complete Weblisk deployment operates as a collaborative, discoverable unit — including marketplace participation, tiered access, commerce, and federation with other hubs.

Hub Capabilities

• Discovery: Hub advertises its capabilities to the Weblisk marketplace for other hubs to find
• Tiered access: Free tier (limited agents, rate-limited), Pro tier (full access, priority routing)
• Commerce: Hub operators can charge for access to their agents via marketplace billing
• Federation: Hub-to-hub collaboration with trust tiers and data boundary contracts (see Protocol — Federation)
• Registry: Central registry of all local agents, domains, and workflows
• Self-sovereignty: Hub operator has full control — no external dependency required to operate

Deployment Model

hub/
├── orchestrator         # Central coordination
├── gateway/             # Application edge (port 443)
├── admin/               # Operator access (port 8443, separate network)
├── agents/
│   ├── infrastructure/  # 11 system agents (always running)
│   └── domains/         # Business domain controllers + work agents
├── storage/             # Agent-local SQLite databases
├── config/
│   ├── global.yaml      # Hub-level configuration
│   ├── policies/        # ABAC, rate-limit, safety policies
│   └── federation/      # Peer definitions, data boundaries
└── keys/                # Ed25519 keypairs (orchestrator + agents)

Lifecycle

The lifecycle blueprint defines the continuous optimisation loop — how the system observes, recommends, and acts on improvements over time. This is what makes a Weblisk deployment adaptive rather than static.

The Loop

1. Strategise: Operators define business strategies with measurable targets (via /v1/strategy)
2. Observe: Agents emit observations during task execution — measurements, anomalies, opportunities
3. Recommend: Agents propose changes based on observations and strategy alignment
4. Approve: Recommendations with approval: required wait for human sign-off
5. Execute: Approved recommendations are executed as new tasks
6. Measure: Results feed back into observations — the loop continues

Strategy Structure

{
  "name": "improve-core-web-vitals",
  "status": "active",
  "targets": [
    { "metric": "lcp", "target": "< 2.5s", "current": "3.1s" },
    { "metric": "cls", "target": "< 0.1", "current": "0.05" }
  ],
  "agents": ["perf-analyzer", "image-optimizer", "css-optimizer"],
  "review_frequency": "weekly"
}

Supporting Components

The remaining 8 architecture blueprints define cross-cutting system concerns — persistence, testing, observability, CLI, and security layers.