Skip to main content

🎯 Boilerplate Enhancements – Epic

Purpose: This document defines the goal of a Constellation enhancement focused on non-AI related boilerplate improvements proven by the CBT Buddy POC.

This epic serves as a capability-definition instrument to make the boilerplate enhancements concrete, scoped, and testable. It clarifies:

  • What value the enhancement unlocks
  • What "done" means
  • What not to build

How it works:

  1. This epic defines the concrete goal: a stable, production-ready boilerplate
  2. We extract the reusable enhancements from the POC into Constellation
  3. We validate them via continued use in Constellation and future fork products
  4. Once validated, this epic can be archived

This epic is NOT:

  • A product Constellation ships (products are built in forks)
  • A long-term maintained doc (temporary, for capability definition)
  • Part of the platform itself (it's a goal-definition tool)
  • About AI capabilities (those belong in Text Intelligence Epic)

See Constellation Roadmap for strategy and context.

Business Value​

Why this epic matters:

  • Production Safety: Fixes critical issues (schema validation, connection pooling, security vulnerabilities) that prevent production failures
  • Security First: Addresses critical security vulnerabilities (CORS, JWT validation, CSRF, password policies) identified in code analysis
  • Reliability: Fixes unsafe patterns (Optional.get(), missing transactions) that cause runtime errors
  • Developer Experience: Improves workflow tools (DDL generation, code quality) that speed up development
  • Foundation for Features: Provides stable infrastructure that all future features (including Text Intelligence) can build on
  • Reduces Technical Debt: Addresses weaknesses in the current boilerplate before adding more features

Value Proposition: A secure, stable, production-ready, developer-friendly boilerplate that enables rapid feature development with confidence.

Scope​

What This Epic Covers​

Critical Security Fixes:

  • CORS configuration (fix wildcard, use allowedOriginPatterns)
  • JWT token validation (proper validation with exception handling)
  • CSRF protection (enable with cookie-based tokens, exclude webhooks)
  • Password validation (enforce complexity requirements)
  • Rate limiting (protect auth endpoints from brute force)
  • Secret externalization (move hardcoded secrets to environment variables)

Critical Production Fixes:

  • Database schema validation (prevents schema drift in production)
  • Connection pool configuration (prevents resource exhaustion)
  • Unsafe Optional usage (fix runtime exceptions)
  • Transaction management (add @Transactional annotations)
  • Environment configuration (fix production URLs, profile-based settings)

Infrastructure Enhancements:

  • Production monitoring (Actuator health checks)
  • Code generation infrastructure (OpenAPI Generator foundation)
  • JSON serialization fixes (Java 8 date/time support)

Developer Experience:

  • Code quality enforcement (Checkstyle)
  • Schema generation workflow (DDL generation task and profile)
  • Enhanced debugging (logging configuration)
  • Input validation (add @Valid annotations)
  • Exception handling improvements (specific exceptions, not generic catch-all)

Test Infrastructure:

  • Test profile improvements (Flyway disable in tests)

Test Coverage & Quality Assurance:

  • Integration tests for critical flows (auth, payments, user management)
  • Unit tests for service layer (authentication, Stripe, email)
  • Repository tests with test database
  • API endpoint tests (MockMvc or RestAssured)
  • Frontend component tests (beyond stubs)
  • Test data builders and fixtures

API Contracts & Documentation:

  • OpenAPI 3.0 specifications for all endpoints
  • SpringDoc annotations on controllers
  • API contract testing (Spring Cloud Contract or Pact)
  • Generated Swagger UI documentation
  • Request/response examples and validation

What This Epic Does NOT Cover​

AI Capabilities (Text Intelligence Epic):

  • ❌ ChatModel beans and Ollama configuration
  • ❌ LangChain4j integration
  • ❌ Text Intelligence services
  • ❌ AI migrations (V4-V6, pgvector, RAG)
  • ❌ AI Spring profiles (ai-test, local)
  • ❌ AI-specific OpenAPI generation

Product-Specific Logic:

  • ❌ Business logic
  • ❌ Domain entities (beyond schema sync)
  • ❌ Frontend changes
  • ❌ UI components

Already in Springular:

  • ❌ Authentication, Payments, Email (already implemented)
  • ❌ CI/CD workflows (already present)
  • ❌ Docker Compose setup (already present, only enhancements)

Constellation Planned Features Required​

For this epic goal, Constellation must provide these Planned Features (in priority order):

  1. ✅ 🔐 Security Hardening — Fix critical security vulnerabilities identified in code analysis

    • CORS configuration fix (allowedOriginPatterns instead of wildcard)
    • JWT token validation implementation
    • CSRF enablement with webhook exclusions
    • Password validation policy (complexity requirements)
    • Rate limiting for auth endpoints
    • Secret externalization to environment variables
    • Input validation with @Valid annotations

  2. ✅ 🛡️ Reliability Improvements — Fix unsafe patterns that cause runtime errors

    • Fix unsafe Optional.get() usage (use orElseThrow)
    • Add @Transactional annotations to service methods
    • Improve exception handling (specific exceptions, not generic)
    • Add null checks and validation in critical paths

  3. ✅ ⚙️ Configuration Cleanup — Fix production configuration issues

    • Fix production environment URLs (environment.prod.ts)
    • Move devtools to dev profile only
    • Configure logging to exclude sensitive data
    • Create environment variable templates (.env.template)

  4. ✅ 🧪 Test Coverage Enhancement — Add comprehensive test coverage

    • Integration tests for critical flows (auth, payments, user management)
    • Unit tests for service layer (AuthenticationService, StripeService, EmailService)
    • Repository tests with H2 test database
    • API endpoint tests with MockMvc or RestAssured
    • Frontend component tests (replace stubs with real tests)
    • Test data builders and fixtures for maintainable tests

  5. ✅ 📋 API Contract & Documentation — Establish API contracts and generate documentation

    • OpenAPI 3.0 specifications for all REST endpoints
    • SpringDoc @Operation and @ApiResponse annotations on controllers
    • API contract testing with Spring Cloud Contract or Pact
    • Generated Swagger UI documentation at /swagger-ui
    • Request/response examples and schema validation
    • API versioning strategy

  6. ✅ 🗄️ Database Schema & Validation — Ensures database schema matches JPA entities and prevents schema drift

    • V3 schema synchronization migration
    • Hibernate ddl-auto: validate configuration
    • DDL generation profile and task

  7. ✅ 🏭 Production Infrastructure — Production-ready infrastructure and monitoring

    • Hikari connection pool configuration
    • Spring Boot Actuator (monitoring)
    • JacksonConfiguration JavaTimeModule (date/time serialization)

  8. ✅ 🛠️ Code Quality & Developer Experience — Enforce code quality and improve developer workflow

    • Checkstyle configuration (strict enforcement)
    • Checkstyle suppressions file (exclude generated sources)
    • Hibernate logging configuration
    • Detailed logging configuration

  9. ✅ 🔧 Code Generation Infrastructure — General-purpose code generation setup

    • OpenAPI Generator foundational setup (Gradle plugin, configuration, test with toy spec)
    • Checkstyle suppressions for generated sources

  10. ✅ 🧪 Test Infrastructure — Clean test execution

  • Test profile Flyway disable configuration

Note: Features are now numbered in sequential priority order (1-10). Security and reliability fixes come first, followed by testing/documentation, then infrastructure foundation.

Success Criteria​

This epic is successful when:

  • ✅ All critical security vulnerabilities are fixed (CORS, JWT, CSRF, passwords, rate limiting)
  • ✅ All critical reliability issues are addressed (Optional usage, transactions, exception handling)
  • ✅ All critical production issues are fixed (schema validation, connection pooling, environment config)
  • ✅ Production infrastructure is in place (monitoring, connection pooling, JSON serialization)
  • ✅ Developer experience is improved (code quality, workflow tools, debugging, validation)
  • ✅ Code generation infrastructure is available for future use (OpenAPI Generator)
  • ✅ Test infrastructure is clean and reliable
  • ✅ Configuration is production-ready (no hardcoded secrets, correct URLs, profile-based settings)
  • ✅ Test coverage is comprehensive (integration, unit, API endpoint tests)
  • ✅ API contracts are documented (OpenAPI specs, Swagger UI, contract tests)

Constellation enhancement is complete when:

  • ✅ All Planned Features (1-10) are implemented
  • ✅ All changes are validated (code builds, tests pass, schema validates)
  • ✅ Security audit passes (no critical/high vulnerabilities)
  • ✅ Test coverage is >70% for critical paths (auth, payments, user management)
  • ✅ API documentation is complete and accessible via Swagger UI
  • ✅ API contract tests pass (frontend/backend compatibility verified)
  • ✅ Documentation complete
  • ✅ Boilerplate is secure, stable, tested, and production-ready

Note: This epic improves the foundation with a security-first approach. Success is measured by security posture, stability, developer experience, and readiness for future features. Product-specific metrics belong to fork products, not Constellation.

Non-Goals​

What this epic is NOT building:

  • ❌ User-facing features (those belong in Feature docs)
  • ❌ AI capabilities (Text Intelligence Epic)
  • ❌ Product-specific logic
  • ❌ Frontend enhancements
  • ❌ New integrations beyond OpenAPI Generator foundation

Keep it focused: Fix tech debt, add foundational infrastructure, improve developer experience. Nothing more.

Implementation Approach​

Source: All enhancements are proven in the CBT Buddy POC and validated in production use.

Method:

  1. Port changes directly from POC (they're already tested)
  2. Validate in Constellation (build, test, verify)
  3. Document in Solution Architecture and Implementation Guides
  4. Use in future fork products to validate

No invention: This epic ports proven patterns, doesn't create new ones.

Source Validation​

This epic addresses issues identified through code analysis and security audit.

Code Analysis Issues Addressed:

Critical Security:

  • ✅ CORS Wildcard Configuration (CRITICAL) - Feature 1: Security Hardening
  • ✅ Missing JWT Token Validation (CRITICAL) - Feature 1: Security Hardening
  • ✅ CSRF Disabled Globally (CRITICAL) - Feature 1: Security Hardening
  • ✅ Hardcoded Stripe Keys (HIGH) - Feature 1: Security Hardening
  • ✅ Weak JWT Secret (HIGH) - Feature 1: Security Hardening
  • ✅ No Password Validation (HIGH) - Feature 1: Security Hardening
  • ✅ Missing Rate Limiting (HIGH) - Feature 1: Security Hardening

Critical Reliability:

  • ✅ Unsafe Optional.get() (CRITICAL) - Feature 2: Reliability Improvements
  • ✅ Flyway + Hibernate DDL Conflict (CRITICAL) - Feature 6: Database Schema & Validation
  • ✅ Missing Transaction Management (HIGH) - Feature 2: Reliability Improvements
  • ✅ Generic Exception Catching (MEDIUM) - Feature 2: Reliability Improvements
  • ✅ Missing Null Checks (HIGH) - Feature 2: Reliability Improvements

Critical Configuration:

  • ✅ Environment Configuration Mismatch (CRITICAL) - Feature 3: Configuration Cleanup
  • ✅ Development Tools in Production (HIGH) - Feature 3: Configuration Cleanup
  • ✅ Missing Request/Response Logging Config (MEDIUM) - Feature 3: Configuration Cleanup
  • ✅ No Database Connection Pool Config (HIGH) - Feature 7: Production Infrastructure

Infrastructure & Best Practices:

  • ✅ No Health Checks Configured (HIGH) - Feature 7: Production Infrastructure
  • ✅ Missing API Documentation (MEDIUM) - Feature 5: API Contract & Documentation
  • ✅ Inadequate Logging (MEDIUM) - Feature 8: Code Quality & Developer Experience
  • ✅ Missing Input Validation (MEDIUM) - Feature 1: Security Hardening

Quality Assurance & Documentation (from codebase exploration):

  • ✅ No Integration Tests (CRITICAL) - Feature 4: Test Coverage Enhancement
  • ✅ Minimal Unit Tests (HIGH) - Feature 4: Test Coverage Enhancement
  • ✅ No API Contract Tests (HIGH) - Feature 5: API Contract & Documentation
  • ✅ No OpenAPI Specifications (MEDIUM) - Feature 5: API Contract & Documentation
  • ✅ Frontend Test Stubs Only (MEDIUM) - Feature 4: Test Coverage Enhancement

Total Issues Addressed: 27 of 32 identified issues (remaining 5 are lower priority or product-specific)

Dependencies​

Epic 2 has NO dependencies:

  • ✅ Can be implemented independently
  • ✅ Does not require Text Intelligence Epic
  • ✅ Does not require any other features

Text Intelligence Epic optionally depends on Epic 2:

  • OpenAPI Generator foundation (optional, Text Intelligence can use manual DTOs)
  • JacksonConfiguration JavaTimeModule (recommended, but Text Intelligence can add if needed)
  • Production readiness fixes (recommended, should be done first)

Recommendation: Do Epic 2 first, then Text Intelligence can use the foundation.

Validation​

This epic is validated when:

  • ✅ All Planned Features are implemented and tested
  • ✅ Boilerplate is stable and production-ready
  • ✅ Future features (e.g., Text Intelligence) can build on this foundation
  • ✅ Developer experience is measurably improved

Validation method: Continued use in Constellation and fork products demonstrates the enhancements work.