CacheFlow Spring Boot Starter

A Spring Boot starter implementing Russian Doll caching patterns with multi-level cache hierarchy (Local → Redis → Edge).

Project Structure

src/main/kotlin/io/cacheflow/spring/
├── annotation/          # Cache annotations (@CacheFlow, @CacheFlowEvict)
├── aspect/             # AOP aspects for caching interception
├── autoconfigure/      # Spring Boot auto-configuration
├── dependency/         # Dependency tracking and resolution
├── fragment/          # Fragment caching implementation
├── versioning/        # Cache versioning system
└── service/           # Core cache services

Quick Commands

Build and Test

# Full build with tests and quality checks
./gradlew build

# Run tests only
./gradlew test

# Run with coverage report
./gradlew test jacocoTestReport

# Code quality analysis
./gradlew detekt

# Security scan
./gradlew dependencyCheckAnalyze

Development Workflow

# Quality gate (run before commits)
./gradlew detekt test jacocoTestReport

# Clean build
./gradlew clean build

# Generate documentation
./gradlew dokka

Key Features

Russian Doll Caching: Nested fragment composition with dependency tracking
Multi-level Cache: Local → Redis → Edge cache hierarchy
Automatic Invalidation: Dependency-based cache invalidation
Spring Boot Integration: Auto-configuration and starter patterns
Performance Monitoring: Metrics and observability built-in

Current Focus

Working on

feature/caching-improvement

branch with:

Comprehensive testing framework
Enhanced dependency tracking
Fragment composition features
Performance optimizations

Code Standards

Test Coverage: Maintain 90%+ coverage
Code Quality: Zero Detekt violations
Documentation: KDoc for all public APIs
Security: Input validation and secure patterns
Performance: Sub-millisecond cache operations

Architecture Patterns

Fragment Caching

@CacheFlowFragment(
    key = "user-profile:#{id}",
    dependencies = ["user:#{id}", "settings:#{id}"],
    ttl = 1800L
)
fun renderUserProfile(@PathVariable id: Long): String

Dependency Tracking

@CacheFlowEvict(patterns = ["user:#{id}"])
fun updateUser(id: Long, user: User)

Fragment Composition

@CacheFlowComposition(
    fragments = ["header:#{userId}", "content:#{userId}", "footer:global"]
)
fun renderUserPage(@PathVariable userId: Long): String

Testing Strategy

Unit Tests: 60-70% of test suite
Integration Tests: 20-30% with Spring context
Performance Tests: 5-10% for benchmarking
Coverage Target: 90%+ for all components

Common Tasks

Adding New Features

Follow Russian Doll caching patterns
Implement comprehensive tests first
Add proper dependency tracking
Update documentation
Verify performance impact

Bug Fixes

Write failing test first
Implement minimal fix
Verify no regression
Update docs if needed
Check performance impact

Refactoring

Ensure backward compatibility
Maintain test coverage
Preserve performance
Update documentation
Follow existing patterns

Important Files

```
AI_MAINTENANCE_RULES.md
```
- Comprehensive AI guidelines
```
.ai-context.md
```
- Project context for AI assistants
```
.ai-patterns.md
```
- Code patterns and examples
```
docs/RUSSIAN_DOLL_CACHING_GUIDE.md
```
- Implementation guide

Quality Gates

All changes must pass:

✅ Detekt analysis (zero violations)
✅ Test suite (90%+ coverage)
✅ Security scan (no high severity)
✅ Performance benchmarks
✅ Documentation updates

Project Structure

src/main/kotlin/io/cacheflow/spring/
├── annotation/          # Cache annotations (@CacheFlow, @CacheFlowEvict)
├── aspect/             # AOP aspects for caching interception
├── autoconfigure/      # Spring Boot auto-configuration
├── dependency/         # Dependency tracking and resolution
├── fragment/          # Fragment caching implementation
├── versioning/        # Cache versioning system
└── service/           # Core cache services

Quick Commands

# Full build with tests and quality checks
./gradlew build

# Run tests only
./gradlew test

# Run with coverage report
./gradlew test jacocoTestReport

# Code quality analysis
./gradlew detekt

# Security scan
./gradlew dependencyCheckAnalyze

# Quality gate (run before commits)
./gradlew detekt test jacocoTestReport

# Clean build
./gradlew clean build

# Generate documentation
./gradlew dokka

Key Features

Russian Doll Caching: Nested fragment composition with dependency tracking

Multi-level Cache: Local → Redis → Edge cache hierarchy

Automatic Invalidation: Dependency-based cache invalidation

Spring Boot Integration: Auto-configuration and starter patterns

Performance Monitoring: Metrics and observability built-in

Architecture Patterns

@CacheFlowFragment(
    key = "user-profile:#{id}",
    dependencies = ["user:#{id}", "settings:#{id}"],
    ttl = 1800L
)
fun renderUserProfile(@PathVariable id: Long): String

@CacheFlowEvict(patterns = ["user:#{id}"])
fun updateUser(id: Long, user: User)

@CacheFlowComposition(
    fragments = ["header:#{userId}", "content:#{userId}", "footer:global"]
)
fun renderUserPage(@PathVariable userId: Long): String

Common Tasks

Follow Russian Doll caching patterns

Implement comprehensive tests first

Add proper dependency tracking

Update documentation

Verify performance impact

Write failing test first

Implement minimal fix

Verify no regression

Update docs if needed

Check performance impact

Ensure backward compatibility

Maintain test coverage

Preserve performance

Update documentation

Follow existing patterns

CacheFlow Spring Boot Starter

Related Skills

Nano Banana Pro

Markdown Converter

1password