diff options
| -rw-r--r-- | CLAUDE.md | 126 |
1 files changed, 126 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..3b3ea10 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,126 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Development Commands + +### Running the Application +```bash +./mvnw quarkus:dev +``` +Run with live reloading enabled for development. + +### Building and Testing +```bash +./mvnw package # Build JAR and Docker image +./mvnw package -Pnative # Build native image with GraalVM +./mvnw spotless:apply # Apply Google Java Format +./mvnw spotless:check # Check code formatting +ant web # Bundle web scripts and stylesheets +ant clean # Clean all build artifacts +``` + +### Web Resources +```bash +ant web # Build web resources (CSS, JS) +ant web.resources # Generate web resources only +ant web.check # Run Flow and ESLint checks +``` + +### Database +```bash +./mvnw liquibase:update # Apply database migrations +./mvnw liquibase:rollback # Rollback database changes +``` + +### Deployment +```bash +ant deploy # Deploy to Kubernetes +``` + +## Project Architecture + +MulkCMS2 is a Java-based CMS built with Quarkus, featuring a hybrid architecture with two main systems: + +### Core Packages +- **benki/** - Modern CMS functionality (posts, bookmarks, wiki, users, chat) +- **cms/** - Legacy CMS system (articles, traditional pages, legacy journal) +- **common/** - Shared utilities (markdown, hibernate, logging, templates) + +### Key Architectural Patterns +- **Post Abstraction**: All content types inherit from `Post` base class +- **Dual User Systems**: Both `benki.users.User` and `cms.users.User` exist for legacy compatibility +- **Panache ORM**: Uses Quarkus Panache for simplified Hibernate operations +- **Role-based Security**: Complex visibility controls (PUBLIC, SEMIPRIVATE, PRIVATE, DISCRETIONARY) + +### Technology Stack +- **Framework**: Quarkus 3.24.2 +- **Database**: PostgreSQL with Hibernate ORM 7.0.4 +- **Authentication**: OIDC/Keycloak (prod), embedded users (dev) +- **Templates**: Qute +- **Build**: Maven + Ant for web resources +- **Containerization**: Docker via Jib + +## Development Environment + +### Database Setup +- Development: PostgreSQL at localhost:5432/mulkcms +- Production: PostgreSQL at postgresql.system:5432/mulkcms +- Uses Liquibase for schema management + +### Authentication +- Development: Embedded user system (user: mulk, password: mulk, role: Admin) +- Production: OIDC with Keycloak at login.benkard.de + +### Configuration Profiles +- `%dev.*` - Development configuration +- `%prod.*` - Production configuration +- Configuration in `src/main/resources/application.properties` + +## Important File Locations + +### Configuration +- `src/main/resources/application.properties` - Main configuration +- `src/main/resources/db/changeLog.xml` - Liquibase migrations +- `pom.xml` - Maven dependencies and build configuration +- `build.xml` - Ant build script for web resources + +### Templates +- `src/main/resources/templates/` - Qute templates +- `src/main/resources/META-INF/resources/` - Static web resources + +### Entity Packages +- `src/main/java/eu/mulk/mulkcms2/benki/` - Entities for microblogging, inherited from Benki +- `src/main/java/eu/mulk/mulkcms2/cms/` - Entities for ordinary blogging, inherited from MulkCMS 1.x + +## Code Style and Standards + +- **Google Java Format**: Enforced via Spotless plugin +- **Import Order**: java,javax,org,com,de,io,dagger,eu.mulk +- **Java**: Target version 17; prefer to use the newest features +- **Annotations**: Uses JetBrains, JSR305, and basic annotations + +## Common Development Tasks + +### Adding New Content Types +1. Create entity extending `Post` in benki/ package +2. Add corresponding REST resource class +3. Create Qute templates if needed +4. Update database schema via Liquibase + +### Working with Database +- All entities use Panache for simplified ORM +- PostgreSQL-specific features extensively used +- Full-text search available via custom Hibernate functions + +### Frontend Development +- Web resources managed by Ant build script +- Uses Snowpack for module bundling +- Parcel for final asset bundling +- ESLint and Flow for code quality + +### Security Considerations +- Role-based access control throughout +- Visibility controls on all content +- CSRF protection via Quarkus security +- Multiple authentication backends supported |