diff --git a/README.md b/README.md index 4316f3a..e01f4e7 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ Phase tracking: - [Phase 3 — Modern Java implementation variants](docs/phase-3-modern-java-variants.md) - [Phase 4 — Cloud-native + observability examples](docs/phase-4-cloud-native-observability.md) - [Phase 5 — AI-era additions (high practical value)](docs/phase-5-ai-era-patterns.md) +- [Phase 6 — Documentation UX for workplace reuse](docs/phase-6-documentation-ux.md) --- @@ -180,6 +181,16 @@ Package: `src/main/java/org/example/ai` --- + +## Documentation UX quick links + +- **Decision trees + domain guides**: [`docs/phase-6-documentation-ux.md`](docs/phase-6-documentation-ux.md) +- **Copy-paste pattern starter**: [`templates/pattern-starter/`](templates/pattern-starter/) + +Use these assets when deciding what pattern to use and when scaffolding new pattern examples for workplace reuse. + +--- + ## Project structure ```text diff --git a/docs/phase-1-production-readiness.md b/docs/phase-1-production-readiness.md index 30dc406..f66c240 100644 --- a/docs/phase-1-production-readiness.md +++ b/docs/phase-1-production-readiness.md @@ -24,3 +24,20 @@ This tracker converts the initial improvement plan into concrete repository chec - Raise JaCoCo line coverage threshold from 35% to at least 50%. - Add package-level/module-level coverage rules for critical packages. - Add dependency/license scanning (for example, OWASP Dependency-Check). + +## Final validation snapshot (2026-04-10) + +Phase 1 production-readiness criteria were re-validated after Phase 6 documentation updates. + +| Checkpoint | Validation method | Result | +|---|---|---| +| Pattern index matrix exists with required columns (`Pattern`, `Intent`, `When to use`, `Trade-offs`, `Real-world example`, `Test class`) | Manual verification in `README.md` | ✅ Pass | +| Package naming typo migration plan (`singalton` → `singleton`) documented with compatibility/deprecation approach | Manual verification in `README.md` + this phase tracker | ✅ Pass | +| Quality gates baseline (Checkstyle, SpotBugs, JaCoCo thresholds) enforced through Maven lifecycle | `pom.xml` plugin configuration verification + `mvn verify` execution | ✅ Pass | +| Environment portability docs for enterprise proxy/mirror setup present | Manual verification in `README.md` build troubleshooting section | ✅ Pass | + +Validation command baseline: + +```bash +mvn verify +``` diff --git a/docs/phase-6-documentation-ux.md b/docs/phase-6-documentation-ux.md new file mode 100644 index 0000000..5ad302a --- /dev/null +++ b/docs/phase-6-documentation-ux.md @@ -0,0 +1,150 @@ +# Phase 6 — Documentation UX for workplace reuse + +This phase makes the repository faster to navigate and reuse in real delivery teams by adding decision guides, domain-first recipes, and copy-paste starter templates. + +## Status overview + +| Area | Goal | Deliverable | Status | +|---|---|---|---| +| Pattern decision trees | Help engineers answer “Choose this pattern when…” quickly | Decision trees for API/backend, data pipelines, event-driven systems, AI-powered systems | ✅ Completed | +| Quick decision guides by domain | Reduce choice paralysis for common system types | Domain-specific pattern shortlist + anti-pattern warnings | ✅ Completed | +| Copy-paste starter templates | Standardize how new pattern examples are added | Starter template bundle with README + code + test + extension points | ✅ Completed | +| Domain recipes | Show adaptation to enterprise verticals | Fintech, e-commerce, healthcare, logistics tailoring playbooks | ✅ Completed | + +--- + +## Choose this pattern when… (decision trees) + +### 1) API/backend systems + +1. Need to protect unstable dependencies? + - Yes → Start with **Circuit Breaker + Retry + Timeout + Backoff + Idempotency Key**. +2. Need clean integration boundaries? + - Yes → Prefer **Hexagonal Architecture** + **Repository**. +3. Need read/write scaling and separate models? + - Yes → Add **CQRS** (and optionally **Event Sourcing** if full audit/time-travel is required). +4. Need phased migration from legacy API/domain? + - Yes → Use **Strangler Fig** + **Anti-Corruption Layer**. + +### 2) Data pipelines + +1. Need high-throughput asynchronous flow? + - Yes → **Reactive Processing** + **Bulkhead** isolation. +2. Need reliable downstream event publication from database state changes? + - Yes → **Transactional Outbox**. +3. Need compensating actions across multiple processing stages? + - Yes → **Saga** (orchestration first, choreography when domains are stable). +4. Need filter/composition logic across many business rules? + - Yes → **Specification** + **Strategy**. + +### 3) Event-driven systems + +1. Need in-process broadcast to multiple listeners? + - Yes → **Observer**. +2. Need durable event history/audit replay? + - Yes → **Event Sourcing**. +3. Need message failure handling at scale? + - Yes → **Dead Letter Queue** + **Retry with Backoff**. +4. Need idempotent at-least-once delivery handling? + - Yes → **Idempotency Key Store** + explicit dedupe checks. + +### 4) AI-powered systems + +1. Need consistent prompt construction? + - Yes → **Prompt Builder**. +2. Need grounding via enterprise knowledge? + - Yes → **Retrieval Pipeline (RAG-lite)**. +3. Need tool routing and unified AI entrypoint? + - Yes → **Tool/Agent Facade**. +4. Need robustness across model outages/quality variability? + - Yes → **Fallback Model Strategy**. +5. Need policy/safety controls and repeatable quality scoring? + - Yes → **Policy-Enforced LLM Client** + **Evaluation Harness**. + +--- + +## Quick decision guides by domain + +### API/backend + +**Start here:** +- Reliability baseline: Retry, Timeout, Circuit Breaker, Idempotency Key. +- Architecture baseline: Hexagonal + Repository. +- Migration baseline: Strangler + ACL. + +**Avoid:** +- Introducing CQRS/Event Sourcing before reliability + observability are in place. + +### Data pipelines + +**Start here:** +- Reactive Processing, Transactional Outbox, Bulkhead, DLQ. +- Add Saga when pipeline steps cross service or data ownership boundaries. + +**Avoid:** +- Choreography-first Sagas without clear event contracts and trace IDs. + +### Event-driven systems + +**Start here:** +- Observer (local), Outbox + DLQ (distributed), Idempotency (delivery safety). +- Prefer explicit schema/version policy for events. + +**Avoid:** +- Assuming exactly-once delivery semantics without deduplication design. + +### AI-powered systems + +**Start here:** +- Prompt Builder + Retrieval Pipeline + Policy-Enforced LLM Client. +- Add Fallback Model Strategy for availability. +- Use Evaluation Harness to gate prompt/model changes. + +**Avoid:** +- Shipping AI flows without policy checks, redaction, and offline evaluation sets. + +--- + +## Copy-paste starter templates + +Use `templates/pattern-starter/` as the canonical scaffold whenever introducing a new pattern sample. + +Template contents: +- `README.md` — pattern intent, when to use, trade-offs, and rollout guidance. +- `src/main/java/.../PatternTemplate.java` — minimal production-style implementation. +- `src/test/java/.../PatternTemplateTest.java` — executable behavior checks. +- `EXTENSION_POINTS.md` — explicit customization hooks for workplace adaptation. + +This standard is intended to be replicated **for every new pattern contribution**. + +--- + +## Domain recipes (adaptation playbooks) + +### Fintech +- Prioritize: Idempotency Key, Event Sourcing, Saga, Retry with bounded backoff. +- Add: strict audit trails, PII masking policies, deterministic evaluation harnesses for AI-assisted decisions. +- Guardrails: monetary operations must be replay-safe and duplicate-resistant. + +### E-commerce +- Prioritize: CQRS, Saga orchestration, Circuit Breaker, Cache-friendly read models. +- Add: inventory reservation compensation strategies, burst traffic rate limits. +- Guardrails: protect checkout path with latency budgets and timeout defaults. + +### Healthcare +- Prioritize: ACL, Repository + Specification, Policy-Enforced AI wrappers. +- Add: traceability and privacy-first defaults (PII masking, least-privilege data flow). +- Guardrails: immutable audit events and deterministic rollback/compensation for critical workflows. + +### Logistics +- Prioritize: Event-driven choreography/orchestration, Bulkhead, DLQ, Retry. +- Add: geo/route strategy modules and state-machine based workflow transitions. +- Guardrails: isolate partner integration failures and preserve eventually consistent shipment state. + +--- + +## Suggested acceptance criteria for this phase + +- Domain leads can select a starting pattern set in under 5 minutes. +- New contributors can scaffold a pattern example from template assets in under 15 minutes. +- Reviewers can verify extension points and tests exist before approving new pattern additions. diff --git a/templates/pattern-starter/EXTENSION_POINTS.md b/templates/pattern-starter/EXTENSION_POINTS.md new file mode 100644 index 0000000..73af491 --- /dev/null +++ b/templates/pattern-starter/EXTENSION_POINTS.md @@ -0,0 +1,21 @@ +# Extension Points + +Document how teams should adapt the pattern safely. + +## Required extension points + +1. **Domain policy hook** + - Where business validation rules are injected. +2. **Integration adapter hook** + - Where external system calls are abstracted. +3. **Observability hook** + - Where tracing/metrics/logging can be added. +4. **Failure strategy hook** + - Where retry/timeout/circuit-break behavior can be configured. + +## Workplace adaptation checklist + +- Fintech: add idempotency and immutable audit IDs. +- E-commerce: add timeout budgets and stock consistency rules. +- Healthcare: add privacy filters and access-control checks. +- Logistics: add routing strategy and asynchronous compensation hooks. diff --git a/templates/pattern-starter/README.md b/templates/pattern-starter/README.md new file mode 100644 index 0000000..13effcc --- /dev/null +++ b/templates/pattern-starter/README.md @@ -0,0 +1,31 @@ +# Pattern Starter Template + +Use this folder as the base for adding a new pattern to the repository. + +## What to include + +1. **Intent**: one sentence on the design problem solved. +2. **When to use**: concrete triggering conditions. +3. **Trade-offs**: at least two downside risks. +4. **Real-world mapping**: one enterprise scenario. +5. **How to run tests**: exact Maven command. + +## Pattern metadata checklist + +- Pattern name: +- Category (creational/structural/behavioral/enterprise/etc.): +- Target package: +- Key dependencies (if any): +- Related test class: + +## Required files + +- `src/main/java/.../PatternTemplate.java` +- `src/test/java/.../PatternTemplateTest.java` +- `EXTENSION_POINTS.md` + +## Definition of done + +- Example compiles. +- Test verifies positive and negative/edge behavior. +- Extension points documented for workplace customization. diff --git a/templates/pattern-starter/src/main/java/org/example/template/PatternTemplate.java b/templates/pattern-starter/src/main/java/org/example/template/PatternTemplate.java new file mode 100644 index 0000000..c8f136b --- /dev/null +++ b/templates/pattern-starter/src/main/java/org/example/template/PatternTemplate.java @@ -0,0 +1,16 @@ +package org.example.template; + +/** + * Minimal starter class for a new pattern contribution. + */ +public class PatternTemplate { + private final String input; + + public PatternTemplate(String input) { + this.input = input; + } + + public String execute() { + return "processed:" + input; + } +} diff --git a/templates/pattern-starter/src/test/java/org/example/template/PatternTemplateTest.java b/templates/pattern-starter/src/test/java/org/example/template/PatternTemplateTest.java new file mode 100644 index 0000000..97ded05 --- /dev/null +++ b/templates/pattern-starter/src/test/java/org/example/template/PatternTemplateTest.java @@ -0,0 +1,14 @@ +package org.example.template; + +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +class PatternTemplateTest { + + @Test + void executeShouldPrefixProcessed() { + PatternTemplate template = new PatternTemplate("sample"); + assertEquals("processed:sample", template.execute()); + } +}