CacheFlow Spring Boot Development

Expert assistant for developing and maintaining the CacheFlow Spring Boot starter library, implementing Russian Doll caching patterns with multi-level cache hierarchy (Local → Redis → Edge).

Project Overview

CacheFlow is a Spring Boot starter library providing:

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

```

Development Workflow

Step 1: Quality Gate Check

Before making any code changes, run the quality gate to establish baseline:

```bash

./gradlew detekt test jacocoTestReport

```

Step 2: Code Analysis

For code understanding or modification tasks:

1. Read relevant source files from `src/main/kotlin/io/cacheflow/spring/`

2. Review associated test files from `src/test/kotlin/`

3. Check `AI_MAINTENANCE_RULES.md` for guidelines

4. Review `.ai-patterns.md` for code patterns

Step 3: Implementation

Follow these principles:

Step 4: Testing and Validation

Run full test suite with coverage:

```bash

./gradlew test jacocoTestReport

```

Verify:

Step 5: Documentation

Update relevant documentation:

Common Tasks

Adding New Cache Features

**Pattern:**

```kotlin

@CacheFlowFragment(

key = "resource:#{id}",

dependencies = ["parent:#{parentId}", "config:global"],

ttl = 1800L

)

fun fetchResource(@PathVariable id: Long): Resource

```

**Steps:**

1. Define annotation in `annotation/` package

2. Implement AOP aspect in `aspect/` package

3. Add dependency tracking in `dependency/` package

4. Write comprehensive tests (unit + integration)

5. Update documentation

Implementing Cache Eviction

**Pattern:**

```kotlin

@CacheFlowEvict(patterns = ["resource:#{id}", "list:*"])

fun updateResource(id: Long, resource: Resource)

```

**Steps:**

1. Identify dependency patterns

2. Implement eviction logic in service layer

3. Add aspect to intercept method calls

4. Test invalidation cascade

5. Verify performance impact

Fragment Composition

**Pattern:**

```kotlin

@CacheFlowComposition(

fragments = ["header:#{userId}", "content:#{userId}", "footer:global"]

)

fun renderPage(@PathVariable userId: Long): String

```

**Steps:**

1. Define fragment boundaries

2. Implement dependency resolution

3. Add composition service

4. Test fragment assembly

5. Benchmark composition performance

Build Commands

Development

```bash

Full build with tests

./gradlew build

Run tests only

./gradlew test

Code quality analysis

./gradlew detekt

Security scan

./gradlew dependencyCheckAnalyze

Clean build

./gradlew clean build

```

Quality Assurance

```bash

Complete quality gate

./gradlew detekt test jacocoTestReport

Coverage report location

./gradlew test jacocoTestReport

Report: build/reports/jacoco/test/html/index.html

Generate API documentation

./gradlew dokka

```

Code Standards

Test Coverage Requirements

Code Quality Requirements

Security Patterns

Important Files

When working on this project, always consider:

Testing Strategy

Unit Tests

Focus on individual components:

Integration Tests

Test with Spring context:

Performance Tests

Benchmark critical paths:

Troubleshooting

Common Issues

**Cache not invalidating:**

1. Check dependency patterns

2. Verify aspect ordering

3. Review transaction boundaries

4. Inspect cache hierarchy

**Poor performance:**

1. Profile cache operations

2. Check fragment size

3. Review dependency depth

4. Optimize key generation

**Test failures:**

1. Check test isolation

2. Verify Spring context

3. Review mock configurations

4. Check async operations

Architecture Principles

1. **Russian Doll Caching**: Always use nested fragments with clear dependencies

2. **Hierarchy First**: Local → Redis → Edge cache levels

3. **Dependency Tracking**: Explicit and automatic dependency resolution

4. **Spring Integration**: Follow Spring Boot auto-configuration patterns

5. **Performance**: Sub-millisecond operations, minimal overhead

6. **Observability**: Metrics and monitoring built-in

Constraints

Example Usage

When helping users implement CacheFlow in their projects:

```kotlin

// Basic caching

@CacheFlow(key = "user:#{id}", ttl = 3600L)

fun getUser(id: Long): User

// Fragment with dependencies

@CacheFlowFragment(

key = "profile:#{userId}",

dependencies = ["user:#{userId}", "settings:#{userId}"]

)

fun renderProfile(userId: Long): String

// Composition

@CacheFlowComposition(

fragments = ["header", "profile:#{userId}", "footer"]

)

fun renderPage(userId: Long): String

// Eviction

@CacheFlowEvict(patterns = ["user:#{id}", "profile:#{id}"])

fun updateUser(id: Long, user: User)

```