The recommended way to build Java services at our organization.
| Category | Features |
|---|---|
| Core | Spring Boot 3.4, Java 21, Gradle/Maven |
| Observability | OpenTelemetry + Grafana, Prometheus metrics, structured logging |
| Resilience | Circuit breakers, retries, rate limiting, graceful degradation |
| Security | OWASP scanning, secrets detection, security headers, request signing |
| Data | PostgreSQL, MySQL, DynamoDB, Redis, Flyway migrations |
| Messaging | SQS, SNS, transactional outbox |
| AI | Spring AI, LangChain4j, OpenAI, Anthropic, Bedrock |
| Enterprise | Multi-tenancy, idempotency, audit logging, distributed locking |
| Testing | JUnit 5, TestContainers, ArchUnit, Pact contract testing |
| DevEx | Makefile, docker-compose, pre-commit hooks, OpenAPI docs |
- Go to Backstage Software Catalog
- Select "Java Service (Golden Path)"
- Fill in the form (see Decision Guide for help)
- Click "Create"
- Clone your new repository and start building!
your-service/
├── src/
│ ├── main/java/ # Application code
│ └── test/java/ # Tests (unit, integration, contract)
├── k8s/ # Kubernetes manifests
├── .github/ # CI/CD workflows
├── docs/ # Documentation
│ ├── GETTING_STARTED.md # First steps
│ ├── PATTERNS.md # Enterprise patterns
│ ├── EXTENDING.md # Customization guide
│ └── adr/ # Architecture decisions
├── docker-compose.yaml # Local development
├── Makefile # Developer commands
└── README.md # Service documentation
| Document | Description |
|---|---|
| Decision Guide | How to choose template options |
| Golden Path Overview | What and why |
| Getting Started | First steps after generation |
| Patterns Guide | Enterprise patterns with examples |
| Extending Guide | How to customize |
- Java Version: 21 (recommended) or 17
- Spring Boot: 3.4 (latest) or 3.3
- Database: None, Aurora PostgreSQL, Aurora MySQL, DynamoDB
- Cache: None, ElastiCache Redis
- Messaging: None, SQS, SNS+SQS
- None: No AI features
- Spring AI: Spring-native abstraction (OpenAI, Anthropic, Bedrock)
- LangChain4j: Full AI toolkit (RAG, agents, tools)
- Direct SDKs: OpenAI, Anthropic, or Bedrock directly
- Feature Flags: Togglz for gradual rollouts
- TestContainers: Container-based integration tests
- ArchUnit: Architecture validation in CI
Every generated service includes these patterns (ready to use):
| Pattern | Purpose | Usage |
|---|---|---|
| Idempotency | Safe retries | @IdempotencyKey annotation |
| Audit Logging | Compliance | @AuditLog annotation |
| Distributed Locking | Prevent races | @DistributedLock or service |
| Graceful Degradation | Handle failures | FallbackService |
| API Deprecation | Sunset old APIs | @ApiDeprecation annotation |
| Multi-tenancy | SaaS isolation | TenantContext |
| Transactional Outbox | Reliable events | OutboxService |
| Request Signing | Service auth | RequestSigningService |
See Patterns Guide for detailed examples.
We've made opinionated choices. Each is documented with rationale:
- ADR-0001: Spring Boot 3 with Java 21
- ADR-0002: Datadog for Observability
- ADR-0003: AI Integration Options
- ADR-0004: Enterprise Patterns
- Slack: #platform-help
- Office Hours: Thursdays 2-3pm
- Issues: Open in this repository
This template evolves based on team feedback and production learnings.
- Open an issue describing the problem or enhancement
- Discuss with platform team
- Submit PR with changes
- Include ADR for significant changes
- Solves a common problem
- Has been proven in production
- Doesn't add unnecessary complexity
- Has clear documentation
- Maintains backward compatibility
| Version | Date | Changes |
|---|---|---|
| 1.0.0 | 2025-12 | Initial release |
🤘 Platform Team