P-01
API-First
The OpenAPI spec is written before any implementation. Models are generated from the spec. No handwritten request or response DTOs. The spec is the contract — everything else is derived.
The engineering standard
every PLRX agent
is built on.
The PLRX Enterprise Agents is not a starter kit or a tutorial. It is the same codebase structure — with the same A2A compliance layer, the same API contract, the same testing pyramid, the same CI/CD pipeline, the same security standards — used to build every specialist agent running in production today. The Clinical Documentation Specialist, the Billing Service Agent, the Data Scientist Agent — all built from this foundation. All held to the same bar.
01
PROJECT LAYOUT
Layered architecture.
Strict boundaries.
Every PLRX agent follows the same layered architecture: API contract first, generated models from the spec, controllers that delegate immediately to a service layer, services that own all business logic, repositories that own all persistence. No exceptions.
Controllers are thin. A controller implements the generated API interface, validates the request at the boundary, and delegates to the service layer in a single call. Zero business logic in controllers. Every request body validated against the OpenAPI spec before the controller body executes.
Services are transactional. Business logic lives in the service layer only. Read-only operations use lightweight read transactions. Write operations use full transactions. Repositories return optionals — never nulls. Exceptions are domain exceptions, surfaced through a centralized advice layer as structured error responses.
Domain objects are immutable. Value types are records. Entity fields are final where possible. No setters on entities. Defensive copies on all mutable collections. Dependency injection throughout — field injection is banned.
02
A2A COMPLIANCE LAYER
Every agent is a
compliant A2A server.
The template includes a complete A2A compliance layer out of the box. Every agent built from it is a fully compliant A2A server on day one — no additional configuration, no extra scaffolding required.
The Agent Card endpoint at /.well-known/agent.json is auto-generated from the agent's skill registry. Skills are declared once and reflected automatically in the agent card, the A2A dispatch router, and the OpenAPI spec. A new skill is added by registering it — the card, the router, and the docs update without code duplication.
The JSON-RPC 2.0 dispatch layer handles all four A2A methods — message/send, tasks/get, tasks/cancel, tasks/resubscribe — and correlates every task with a PLRX Durable State Machine workflow instance. Task lifecycle transitions are durable. A task that enters input_required state suspends its workflow durably and resumes on signal without losing state.
The idempotency framework enforces exactly-once semantics on every side-effecting activity. Idempotency keys are deterministic — derived from the workflow and activity context. Retries never produce duplicate side effects.
# Incoming A2A request to specialist-agent
POST /
{
"jsonrpc": "2.0", "method": "message/send"
"params": { "message": { "parts": [{ "kind": "data"
"data": {
"skill": "eligibility_verification"
"order_id": "ORD-787"
"idempotency_key":"<deterministic>"
}}]}}
}
── A2A dispatch routes to registered skill handler ──
# TaskLifecycleService
task.state: submitted
workflow.id: wf-ORD-787 # PLRX DSM correlated
idempotency: enforced # deterministic key
── Workflow starts — task transitions to working ──
{
"result": { "id": "task-787"
"status": { "state": "submitted" }
} }
}
03
API-FIRST DESIGN CONTRACT
The spec is written
before any code.
Every PLRX agent exposes its capabilities through an OpenAPI specification. The spec is written first — before implementation begins, before tests are written, before the service layer is designed. The spec is the contract. Everything downstream is derived from it.
All request and response models are generated from the spec. No handwritten DTOs. No duplication between documentation and implementation. The generated models are placed in a package that is not edited — they are outputs of the spec, not inputs to it. If the spec changes, the models change.
Every request body is validated against the spec at the boundary before reaching the controller body. Validation failures return structured error responses responses — structured, machine-readable, consistent across every agent.
The SLA contract is enforced at the test level, not just documented. All synchronous agent endpoints must respond at P99 < 100ms. This assertion is part of the web layer test suite — it runs on every build, and it fails the build if the threshold is breached.
PERFORMANCE SLA
P99 < 100ms
enforced in CI · not just documented
# 1. Write the spec first — source of truth
# agent-service.openapi.yaml
paths:
/api/eligibility:
post:
operationId: executeSkill
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MissionRequest'
── Generate models · never hand-write DTOs ──────────
# 2. Models generated automatically on build
# Generated models — DO NOT EDIT
# MissionRequest ← generated from spec
# MissionResponse ← generated from spec
── Controller implements generated interface ────────
# 3. Controller is thin — validates + delegates
@RestController
class EligibilityController implements EligibilityApi {
@Override
public ResponseEntity executeSkill(
@Valid SkillRequest request) {
// @Valid enforced at boundary — no manual checks
return service.execute(request);
}
}
04
TESTING PYRAMID
80% coverage.
Not negotiable.
Every PLRX agent ships with a testing pyramid. The levels are not optional. The coverage gate — 80% minimum on all business logic — runs on every build and blocks deployment if breached. Generated API models are excluded from the gate.
The pyramid is not documentation. It is a delivery requirement. New features are written test-first. Bug fixes include a failing test that demonstrates the bug before the fix is applied. The test suite is the specification of what the agent does — readable by anyone on the team, not just the engineer who wrote it.
L1
Unit Tests
Business logic in complete isolation. Strict mock boundaries — collaborators are always mocked, never instantiated. Fast. No I/O. No containers. Naming: methodName_scenario_expectedBehavior.
L3
Integration Tests
The full system exercised against all real services with no mocks. Covers complete mission flows across agent boundaries — from orchestrator through specialist agents to external integrations. Validates that every component behaves correctly when connected to production-equivalent infrastructure.
L2
Component Tests
Each service tested as an independent unit. External dependencies — databases, message brokers, dependent services — are provided via test containers and mocks. No live external systems. Tests verify the service contract in full, including persistence and messaging behaviour, without touching anything outside the service boundary.
L4
Performance Tests
A cross-cutting concern that runs across all levels. At the unit level, critical path methods are benchmarked for regression. At the component level, throughput and concurrency are validated under load. At the integration level, P99 < 100ms is enforced on all synchronous agent endpoints and blocks deployment if breached.
05
CI/CD PIPELINE
Push. Build. Deploy.
No manual steps.
Every PLRX agent ships through the same automated pipeline. A push to the main branch triggers the full chain — compile, test, version, containerize, deploy. No manual steps between a merged pull request and pods rolling out on the target cluster. If the pipeline fails at any step, deployment stops and the team is notified.
STAGE 01
Build & Test
- Compile source — API models generated from spec
- Pull dependencies from artifact registry
- Run unit test suite — strict mock boundaries
- Run BDD component tests — real infra containers
- Run integration tests — P99 SLA asserted
- Enforce 80% coverage gate — fail if breached
- Run static analysis — code style + security scan
STAGE 02
Container Image
- Calculate next semantic version (e.g. v0.0.1 → v0.0.2)
- Build container image from Dockerfile
- Tag image with version and commit SHA
- Push versioned image to artifact registry
- Image immutable — never overwritten on push
STAGE 03
Deploy
- Pull Kubernetes deployment manifests
- Apply manifests with new image tag
- Pods roll out on target cluster (AWS)
- Health checks confirm pods healthy
- Rollback triggered automatically on failure
- Deployment event logged to audit trail
06
SECURITY STANDARDS
Security is baked in.
Not bolted on.
Every PLRX agent built from the template ships with non-negotiable security defaults. These are not guidelines or recommendations. They are enforced by the static analysis step in CI — a violation blocks the build.
No hardcoded secrets. All configuration values are injected at runtime from a secure vault. The agent performs a startup validation — if a required configuration value is missing or invalid, it refuses to start. A misconfigured agent does not start silently and fail later. It fails immediately and visibly.
PHI is masked in all log output. A structured masking utility wraps all sensitive fields before they reach the log layer. A log statement cannot accidentally surface a patient name, SSN, or date of birth. The masking is applied at the type level — not per log statement.
No stack traces in error responses. All errors return structured error responses — structured, machine-readable, consistent. The client receives a problem type, a title, a status code, and a detail message. It never receives a stack trace, a class name, or an internal implementation detail.
Constructor injection only. Field injection is statically banned. All dependencies are injected through constructors, making them explicit, immutable, and testable without a dependency injection framework.
# ✓ Required: dependency injection
@Service
class EligibilityService {
private final EligibilityRepository repository;
private final ClearinghouseClient client;
public EligibilityService( // ← dependency injection
EligibilityRepository repository,
ClearinghouseClient client) {
this.repository = repository;
this.client = client;
}
}
── PHI masking — applied at type level ─────────────
# PHI field — masked before any log statement
@PiiField(type = PiiType.PATIENT_NAME)
private final String patientName;
# Log output — PHI never surfaces
# INFO EligibilityService - Patient: [MASKED] checked
── structured error responses — no stack traces ────────
# Error response — structured, no internals exposed
{
"type": "https://plrx.ai/errors/payer-not-found"
"title": "Payer not found"
"status": 404
"detail": "Payer UHC-001 is not configured for tenant"
}
07
ENGINEERING PRINCIPLES
The rules that govern
every line of code.
These are not suggestions. They are the operating principles that every PLRX engineer applies to every agent, every pull request, and every deployment decision. They exist because quality at the level we need cannot be achieved through review alone — it must be built into the way code is written from the start.
P-02
SLA < 100ms P99
Every synchronous API endpoint must respond within 100 milliseconds at P99. This is enforced in the test suite. No exceptions without explicit architectural justification.
P-03
80% Coverage Minimum
JaCoCo coverage gate on all business logic — unit, component, and integration combined. Generated API models excluded. Coverage below 80% blocks the build.
P-04
Secrets-Safe by Default
No hardcoded credentials. Startup validation rejects misconfigured agents. PHI protection enforced at the data layer. structured error responses on all endpoints — no internal detail leaks.
P-05
Immutability First
Records for value types. Final fields where possible. No setters on entities. Defensive copies on mutable collections. Immutability is the default — mutability requires justification.
P-06
Constructor Injection
All dependencies injected through constructors. Field injection is banned and enforced by static analysis. Dependencies are explicit, immutable, and testable without a container.
P-07
Plan Before Execute
Non-trivial changes require a written plan before any code is written. The plan covers requirements, risks, and implementation steps. Ambiguity is resolved upfront — not mid-build.
P-08
Thin Controllers
Controllers implement the generated API interface, validate the request, and delegate to the service layer. Zero business logic in controllers. The controller body is always one meaningful call.
P-09
Demand Elegance
Before shipping a non-trivial change, ask: "Is there a more elegant way?" If a fix feels hacky, it is hacky. Implement the elegant solution — not the expedient one.
The foundation behind 94% autonomous operations.
The PLRX Enterprise Agents is what every specialist agent in production is built on today.
Explore the platform or request access to deploy your first agent fleet.