# Microprofile Server

> Architecture and coding rules for long-running Java MicroProfile / Jakarta EE server applications — BCE layering, business components (BC), JAX-RS resources, CDI, JSON-P, testing (unit/integration/system), and Maven project structure. Use when creating, generating, scaffolding, writing, or reviewing code, resources, entities, boundaries, or business components in MicroProfile server projects. Not for serverless deployments.

- Skill: `adambien/microprofile-server` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add adambien/microprofile-server`
- Raw SKILL.md: https://api.skillmd.com/api/skills/adambien/microprofile-server/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: AdamBien (https://skillmd.com/u/adambien)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/adambien/microprofile-server

---


## Composition
- compose with `java-conventions` for all language-level Java rules (syntax, style, naming, visibility, interfaces/classes, methods/lambdas, streams/collections, exceptions, comments/JavaDoc)
- this skill specializes only the MicroProfile / Jakarta EE server context — it does not restate language-level rules

## Dependencies
- prefer dependencies in this order: Java SE, MicroProfile, Jakarta EE

## Exceptions (JAX-RS)
- in JAX-RS projects, inherit from WebApplicationException for custom exceptions
- use explicit exceptions like BadRequestException for Response.Status.BAD_REQUEST
- throw explicit WebApplicationException subclasses (e.g. BadRequestException, NotFoundException) rather than constructing Response objects inline — they are automatically mapped to the correct HTTP status by the JAX-RS runtime

## BCE/ECB Architecture
- structure code using the Boundary Control Entity (BCE/ECB) pattern
- package structure: [ORGANIZATION_NAME].[PROJECT_NAME].[COMPONENT_NAME].[boundary|control|entity]
- top level package reflects the application responsibility or name
- suggest renaming the top level [PROJECT_NAME] package when it does not reflect the project's name or responsibility
- business components are children of top level package, named after their responsibilities
- a BC may represent a domain concept or a shared concern; both are valid when the responsibility has a name and is reused across the application
- boundary, control, entity packages are only allowed in business components
- a BC does not need every layer; a BC may consist of only a control layer when its responsibility is procedural and consumed by other BCs
- not every BCE component needs a dedicated boundary package; control package contents can be accessed directly
- prefer a dedicated BC over the root application package when a shared concern carries domain or protocol semantics, exposes more than one operation, or is expected to grow
- reserve the root application package for trivial single-class plumbing with no business semantics and no protocol coupling
- do not explain the BCE pattern in documentation

## Boundary Layer
- keep coarse-grained classes in the boundary package
- place facades in the boundary package
- health checks must be placed in the boundary package
- @Transactional is only allowed in boundary layer
- if there is no Boundary stereotype, use ApplicationScope instead

## Control Layer
- implement procedural business logic in the control package

## Entity Layer
- maintain domain objects, data classes, and entities in the entity package
- entities maintain state and corresponding behavior
- model value objects as enums
- direct references between entities from independent BCs are allowed, but always aim for Maximal Cohesion and Minimal Coupling between BCs
- if a relation exists in the database (e.g. JPA foreign key), the entities must carry a corresponding reference (id field or association); the DB schema is the source of truth
- excessive cross-BC references or shared configuration is a refactoring signal — split, merge, or rebalance the BCs to restore cohesion

## Components
- create new components with minimal business logic and essential fields only

## JavaDoc (MicroProfile/Jakarta EE)
- follow links in JavaDoc to external specifications and use them for code generation
- use popular, also funny, technical terms from the Java SE, MicroProfile and Jakarta EE ecosystems as examples in unit tests and javadoc

## README Guidelines
- write brief, 'to the point' README.md files for advanced developers
- use precise and concise language; avoid generic adjectives like "simple", "lightweight"
- do not include detailed project structure (file/folder listings); high-level module descriptions are acceptable
- never list REST resources in READMEs
- if modules are listed, provide links
- do not use "Orchestrates" term; use more specific alternatives

## Integration Tests
- integration tests end with IT suffix and are executed by the failsafe maven plugin (no configuration necessary)

## System Tests (ST)
- system tests are created in a dedicated Maven module ending with "-st"
- use microprofile-rest-client for testing JAX-RS resources
- REST client interfaces: src/main/java of the -st module
- test classes: src/test/java of the -st module
- name client interfaces after the resource with "Client" suffix (e.g., GreetingsResource -> GreetingsResourceClient)
- RegisterRestClient configKey: "service_uri"
- STs end with "IT" suffix
- do not use RestAssured. Write e2e test in the -st module
- execute system tests after every major change to the service module
- in PoC mode (user-activated), system test execution is skipped

## JAX-RS
- resources should be named in plural (e.g., SpeakersResource not SpeakerResource)
- @Consumes and @Produces should be declared on class-level
- do not implement business logic in JAX-RS resources; delegate instead
- prefer returning JAX-RS Response over JsonObject in resources
- do not create new "@RegisterRestClient(configKey," - reuse existing

## JSON Serialization (JSON-P)
- prefer JSON-P over JSON-B
- record entities should ship with toJSON method returning a JSON-P object
- always map JSON-P in the boundary to entities
- create record entities from JSON-P JsonObject in static method: fromJSON(JsonObject json)

## Project Management
- always ask before changing pom.xml
- on opening existing projects, load AGENTS.md (if present) before making changes
- do not create or change any files on opening existing projects; stop after initialization and wait for instructions
- do not generate code initially in an empty project
- Maven pom.xml must not be created for Java 25 CLI applications
- never use quarkus-hibernate-validator
- create metrics and observability features with OTEL / opentelemetry