|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this |
| 4 | +repository. |
| 5 | + |
| 6 | +## Build and Development Commands |
| 7 | + |
| 8 | +This is a Spring Boot 3.x application using Maven with Java 21. |
| 9 | +Code formatting is enforced using the Spring Java Format plugin. |
| 10 | + |
| 11 | +**Build Commands:** |
| 12 | + |
| 13 | +```bash |
| 14 | +./mvnw clean spring-javaformat:apply package # Build application |
| 15 | +./mvnw spring-boot:run # Run application locally |
| 16 | +./mvnw spring-javaformat:apply test # Run all tests |
| 17 | +``` |
| 18 | + |
| 19 | +## Architecture Overview |
| 20 | + |
| 21 | +### Core Structure |
| 22 | + |
| 23 | +- **Package**: `am.ik.blog` - Main application package |
| 24 | +- **Domain**: `am.ik.blog.entry` - Blog entry domain model and repository |
| 25 | +- **Config**: `am.ik.blog.config` - GemFire and application configuration |
| 26 | +- **Markdown**: `am.ik.blog.markdown` - Markdown processing with YAML front matter |
| 27 | +- **Web**: `am.ik.blog.entry.web` - REST API controllers |
| 28 | + |
| 29 | +### Domain Model |
| 30 | + |
| 31 | +- **Entry**: Main blog entry entity with ID, title, content, categories, tags, frontMatter |
| 32 | +- **Author**: Author information with name, URL, GitHub |
| 33 | +- **Category/Tag**: Simple categorization entities |
| 34 | +- **FrontMatter**: YAML metadata container |
| 35 | + |
| 36 | +## Key Dependencies and Patterns |
| 37 | + |
| 38 | +### Technology Stack |
| 39 | + |
| 40 | +- **Spring Boot 3.5** |
| 41 | +- **VMware GemFire 10.1** |
| 42 | +- **Java 21** |
| 43 | +- **Jilt** for builder pattern generation |
| 44 | + |
| 45 | +### Design Patterns |
| 46 | + |
| 47 | +- **Repository Pattern**: `EntryRepository` with dual-source strategy (cache + external API) |
| 48 | +- **Builder Pattern**: Generated via `@Builder` annotation from Jilt |
| 49 | +- **Record Classes**: Used for configuration properties (`EntryProps`) |
| 50 | + |
| 51 | +## Development Requirements |
| 52 | + |
| 53 | +### Prerequisites |
| 54 | + |
| 55 | +- Java 25 runtime |
| 56 | + |
| 57 | +### Code Standards |
| 58 | + |
| 59 | +- Use builder pattern if the number of arguments is more than two |
| 60 | +- Write javadoc and comments in English |
| 61 | +- Spring Java Format enforced via Maven plugin |
| 62 | +- All code must pass formatting validation before commit |
| 63 | +- Use Java 25 compatible features |
| 64 | +- Use modern Java technics as much as possible like Java Records, Pattern Matching, Text Block |
| 65 | + etc ... but don't use "var". |
| 66 | +- Be sure to avoid circular references between classes and packages. |
| 67 | +- Don't use Lombok. |
| 68 | +- Don't use Google Guava. |
| 69 | + |
| 70 | +### Spring Specific Rules |
| 71 | + |
| 72 | +- Always use constructor injection for Spring beans. No `@Autowired` required except for test code. |
| 73 | +- Use `RestClient` for external API calls. Don't use `RestTemplate`. |
| 74 | +- `RestClient` should be used with injected/autoconfigured `RestClient.Builder`. |
| 75 | +- Use `JdbcClient` for database operations. Don't use `JdbcTemplate` except for batch update. |
| 76 | +- Use `@Configuration(proxyBeanMethods = false)` for configuration classes to avoid proxying issues. |
| 77 | +- Use `@ConfigurationProperties` + Java Records for configuration properties classes. Don't use |
| 78 | + `@Value` for configuration properties. |
| 79 | +- Use `@DefaultValue` for non-null default values in configuration properties classes. |
| 80 | + |
| 81 | +### Package Structure |
| 82 | + |
| 83 | +Package structure should follow the "package by feature" principle, grouping related classes |
| 84 | +together. Not by technical layers. |
| 85 | +Exceptionally, web related classes including Controllers should be located in `web` package under the |
| 86 | +feature package. Other layers should not have dedicated packages like "service", "repository", "dto" |
| 87 | +etc... |
| 88 | + |
| 89 | +`web` package should not be shared across different features. Each feature should have its own `web` |
| 90 | +domain objects should be clean and not contain external layers like web or database. |
| 91 | + |
| 92 | +For DTOs, use inner record classes in the appropriate classes. For example, if you have a |
| 93 | +`UserController`, define the request/response class inside that controller class. |
| 94 | + |
| 95 | +### Testing Strategy |
| 96 | + |
| 97 | +: |
| 98 | + |
| 99 | +- **Unit Tests**: JUnit 5 with AssertJ for service layer testing |
| 100 | +- **Integration Tests**: `@SpringBootTest` + Testcontainers for full application context |
| 101 | +- **Test Data Management**: Use `@TempDir` for filesystem testing, maintain test independence |
| 102 | +- All tests must pass before completing tasks |
| 103 | +- Test coverage includes artifact operations, repository browsing, and API endpoints |
| 104 | + |
| 105 | +### After Task completion |
| 106 | + |
| 107 | +- Ensure all code is formatted using `./mvnw spring-javaformat:apply` |
| 108 | +- For each task, notify that the task is complete and ready for review by the following command: |
| 109 | + |
| 110 | +``` |
| 111 | +osascript -e 'display notification "<Message Body>" with title "<Message Title>"’ |
| 112 | +``` |
0 commit comments