context-service-guide

---
name: context-service-guide
description: Navigate and understand any legacy cpp-context-* WildFly/Maven service. LEGACY ONLY — must not be applied to new Spring Boot work. Use when onboarding to a context service, exploring its modules, or understanding its CQRS structure and integrations.
---

> ⚠️ **Legacy WildFly context services only.** The patterns in this skill — `cpp-context-*` Maven multi-modules, `-command-api` / `-query-api` / `-domain-event`, RAML, custom CQRS plumbing, `subscriptions-descriptor.yaml` — are **WildFly-era patterns and must not be applied to new Spring Boot services**. They exist here to help engineers onboard to existing services.
>
> For **new Spring Boot services**, use `skills/springboot-service-from-template/`.
> For **new HMCTS Marketplace API specs**, use `skills/springboot-api-from-template/`.
> Cross-pollinating these patterns into a Spring Boot service is a design regression — the master source for Spring Boot is the HMCTS template (see `context/tech-stack.md`).

# Context Service Guide

Provides a structured walkthrough of any CP context service repository to help developers quickly understand its purpose, structure, integrations, and development workflow.

## When to Use

- User asks to "explain this context service", "walk me through this repo", "what does this service do"
- User is new to a `cpp-context-*` repo and wants to understand it
- User asks about a service's domain events, commands, queries, or integrations

## Process

### Step 1: Identify the Context Service

Determine which `cpp-context-*` repo the user is asking about. If they're in a subdirectory, resolve to the repo root.

### Step 2: Read Key Files

Read these files in parallel to build a complete picture:

1. **`pom.xml`** (root) — parent POM, modules list, properties, dependency versions
2. **`README.md`** — if present, provides an overview
3. **`*-domain/*-domain-event/src/main/resources/json/schema/`** — domain event schemas reveal what the service publishes
4. **`*-command/*-command-api/src/raml/`** — command API RAML definitions reveal what operations the service accepts
5. **`*-query/*-query-api/src/raml/`** — query API definitions reveal what data the service exposes
6. **`*-viewstore-liquibase/`** — Liquibase changelogs reveal the read-model database schema
7. **`*-event-sources/`** — event source configurations reveal what events from other contexts this service subscribes to

### Step 3: Map Integrations

From the POM dependencies and event sources, identify:
- **Upstream contexts** — which other context services publish events this service consumes
- **Downstream contexts** — which contexts consume this service's domain events
- **Shared components used** — audit, auth, reference data, file service, notifications, etc.
- **External systems** — any SOAP/REST integrations with systems outside CP

### Step 4: Identify Module Structure

Map the standard CQRS module layout:

| Module | Purpose | Key classes to look at |
|--------|---------|----------------------|
| `-command-api` | Command definitions | RAML files, JSON schemas |
| `-command-handler` | Command processing | `*CommandHandler.java`, `*Aggregate.java` |
| `-query-api` | Query definitions | RAML files |
| `-query-handler` | Query processing | `*QueryHandler.java` |
| `-domain-event` | Domain events | JSON schemas in resources |
| `-domain-value-schema` | Value objects | JSON schemas |
| `-event-sources` | Event subscriptions | `*EventSource.java` |
| `-viewstore` | JPA read models | `*Entity.java`, `*Repository.java` |
| `-viewstore-liquibase` | DB migrations | `db/changelog/` XML/YAML files |
| `-service` | App orchestration | WildFly deployment descriptors |
| `-integration-test` | Integration tests | Cucumber features, step definitions |

### Step 5: Generate Summary

Output a structured summary:

```
## [Service Name]

### Purpose
One paragraph describing what this bounded context manages.

### Domain Events Published
- event.name.one — description
- event.name.two — description

### Commands Accepted
- command.name.one — description

### Queries Exposed
- query.name.one — description

### Upstream Dependencies
- cpp-context-X — consumes events from...

### Downstream Consumers
- cpp-context-Y — publishes events consumed by...

### Database
- Schema summary from Liquibase

### Development
- mvn clean install
- mvn test -pl {module}
- Integration tests: mvn verify -pl {name}-integration-test
```

## Common Module Patterns

### Event Source Subscription
Look in `*-event-sources` for `@Handles` annotations or event handler methods — these show which domain events from other contexts trigger processing in this service.

### Interceptor Chain
Check for `*InterceptorChainProvider.java` — custom interceptor chains may override default audit/auth behaviour. If absent, the service uses the framework default (audit + access control on all APIs).

### View Store Projections
The `-event-sources` module typically contains projection logic that transforms domain events into viewstore entities. This is the CQRS projection — the bridge between the event store and the read model.

More agent context in hmcts/claude

15 other files this repository gives its agents.