Skip to content

Commit 9516685

Browse files
dmealingclaude
dmealing
and
claude
committed
Add comprehensive Claude AI documentation and automated version management system
- Add CLAUDE.md: Complete project overview, architecture, and development guidelines - Add CLAUDE_ARCHITECTURE.md: Detailed technical architecture and design patterns - Add CLAUDE_COMMANDS.md: Common Maven commands and development workflows - Add CLAUDE_VERSION_MANAGEMENT.md: Automated version update system for all project files - Update CLAUDE.md: Add automatic version management instructions for Claude AI - Update CLAUDE_COMMANDS.md: Add version verification commands and update notes Features: - Automated version updates across all 8+ POM files when Claude is asked to increment versions - Automatic README.md and RELEASE_NOTES.md updates during version changes - Comprehensive project documentation for Claude AI assistant - Build commands, architecture patterns, and development guidelines - Version consistency validation and build verification steps 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent ec6a2eb commit 9516685

6 files changed

Lines changed: 786 additions & 2 deletions

File tree

‎CLAUDE.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# MetaObjects Project - Claude AI Assistant Guide
2+
3+
## Project Overview
4+
MetaObjects is a Java-based suite of tools for metadata-driven development, providing sophisticated control over applications beyond traditional model-driven development techniques.
5+
6+
- **Current Version**: 4.5.0-SNAPSHOT (latest stable: 4.5.0)
7+
- **License**: Apache License 2.0
8+
- **Java Version**: Java 21 (upgraded from Java 1.8)
9+
- **Build Tool**: Maven
10+
- **Organization**: Doug Mealing LLC
11+
12+
## Project Structure
13+
14+
```
15+
├── core/ # Core MetaObjects functionality
16+
├── metadata/ # Metadata models and types
17+
├── maven-plugin/ # Maven plugin for code generation
18+
├── om/ # Object Manager module
19+
├── demo/ # Demo applications (commented out in build)
20+
├── web/ # Web-related utilities (commented out in build)
21+
├── omdb/ # Database Object Manager (commented out in build)
22+
└── docs/ # Documentation
23+
```
24+
25+
## Key Build Commands
26+
27+
```bash
28+
# Build the project
29+
mvn clean compile
30+
31+
# Run tests
32+
mvn test
33+
34+
# Package the project
35+
mvn package
36+
37+
# Generate code using MetaObjects plugin
38+
mvn metaobjects:generate
39+
40+
# Launch MetaObjects Editor (planned feature)
41+
mvn metaobjects:editor
42+
```
43+
44+
## Key Technologies & Dependencies
45+
46+
- **Java 21** with Maven compiler plugin 3.13.0
47+
- **SLF4J + Logback** for logging (migrated from Commons Logging)
48+
- **JUnit 4.13.2** for testing
49+
- **OSGi Bundle Support** via Apache Felix Maven Bundle Plugin
50+
- **Gson 2.13.1** for JSON handling
51+
- **Commons Validator 1.9.0** for validation
52+
- **Maven Build System** with comprehensive plugin configuration
53+
54+
## Core Concepts
55+
56+
### MetaObjects Types
57+
- **ValueMetaObject**: Dynamic objects with public getter/setter access
58+
- **DataMetaObject**: Wrapped objects with protected accessors
59+
- **ProxyMetaObject**: Proxy implementations without concrete classes
60+
- **MappedMetaObject**: Works with Map interface objects
61+
62+
### Key Features
63+
- **Metadata-driven development** with sophisticated control mechanisms
64+
- **Code generation** support for Java interfaces and XML overlays
65+
- **JSON/XML serialization** with custom type adapters
66+
- **Validation framework** with field-level and object-level validators
67+
- **Default field values** support in meta models
68+
- **PlantUML diagram generation** from metadata definitions
69+
- **Maven plugin integration** for build-time code generation
70+
71+
## Recent Major Changes (v4.5.0)
72+
73+
### Java Modernization
74+
- Upgraded from Java 1.8 to Java 21
75+
- Updated Maven compiler to use --release flag
76+
- Resolved OSGi bundle compatibility for Java 21
77+
78+
### Performance Improvements
79+
- Intelligent caching in ArrayValidator
80+
- Optimized getAttrValueAsInt() methods
81+
- Enhanced error handling with fallback strategies
82+
83+
### Code Quality Enhancements
84+
- Migrated from Commons Logging to SLF4J (46 files)
85+
- Replaced StringBuffer with StringBuilder (8 files)
86+
- Added comprehensive JavaDoc documentation
87+
- Resolved 25+ critical TODO items
88+
89+
## Development Guidelines
90+
91+
### Code Style
92+
- Use SLF4J for all logging
93+
- Follow existing naming conventions
94+
- Maintain backward compatibility
95+
- Add comprehensive JavaDoc for public APIs
96+
- Use StringBuilder instead of StringBuffer in non-thread-safe contexts
97+
98+
### Testing
99+
- All modules compile successfully with Java 21
100+
- Comprehensive test coverage required
101+
- Use JUnit 4.13.2 for testing
102+
- Test files should follow existing patterns
103+
104+
### Maven Configuration
105+
- Uses parent POM for dependency management
106+
- OSGi bundle support enabled
107+
- Two distribution profiles: default (Draagon) and nexus (Maven Central)
108+
- Comprehensive plugin configuration for Java 21 compatibility
109+
110+
## Module Dependencies
111+
112+
Build order (important for development):
113+
1. `metadata` - Base metadata models
114+
2. `maven-plugin` - Code generation plugin
115+
3. `core` - Core functionality (depends on generated models)
116+
4. `om` - Object Manager
117+
118+
## Key Files for Development
119+
120+
- `pom.xml` - Main project configuration
121+
- `README.md` - Basic project information
122+
- `RELEASE_NOTES.md` - Detailed version history and features
123+
- `LICENSE` - Apache 2.0 license
124+
- Core source: `core/src/main/java/com/draagon/meta/`
125+
- Metadata: `metadata/src/main/java/com/draagon/meta/`
126+
- Tests: `*/src/test/java/`
127+
128+
## Upcoming Features (v4.4.0 Planned)
129+
130+
- Native support for Abstract and Interface MetaData
131+
- TypedMetaDataLoader enhancements
132+
- Enhanced MetaData IO (YAML, HOCON, TOML support)
133+
- Integrated MetaObjects Editor
134+
- Plugin support for IO readers/writers
135+
- Namespace support in XML serialization
136+
137+
## Development Notes
138+
139+
This project follows metadata-driven development principles where the structure and behavior of applications are controlled through metadata definitions rather than hard-coded implementations. The build system is sophisticated with OSGi bundle support and comprehensive Maven plugin configuration.
140+
141+
For Claude AI: When working with this codebase, pay attention to the metadata-driven architecture and maintain the established patterns for MetaObject implementations, validation, and serialization.
142+
143+
## VERSION MANAGEMENT FOR CLAUDE AI
144+
145+
**CRITICAL**: When user requests "increment version", "update version", or "release new version":
146+
147+
1. **AUTOMATICALLY UPDATE ALL VERSION REFERENCES**:
148+
- All pom.xml files (root + 8 modules)
149+
- README.md "Current Release:" line
150+
- RELEASE_NOTES.md (add new version section)
151+
- CLAUDE.md version references
152+
153+
2. **FOLLOW VERSION STRATEGY**:
154+
- Release: Remove -SNAPSHOT from current version
155+
- Next Dev: Increment version + add -SNAPSHOT
156+
- Ensure ALL modules have identical versions
157+
158+
3. **VERIFY BUILD**: Run `mvn clean compile` after changes
159+
160+
4. **SEE**: CLAUDE_VERSION_MANAGEMENT.md for complete process
161+
162+
This ensures complete version synchronization across the entire project when versions are updated.

‎CLAUDE_ARCHITECTURE.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# MetaObjects Architecture Guide for Claude AI
2+
3+
## Core Architecture Overview
4+
5+
MetaObjects implements a sophisticated metadata-driven development framework where application behavior and structure are controlled through metadata definitions rather than hard-coded implementations.
6+
7+
## Module Architecture
8+
9+
### Build Dependency Order
10+
```
11+
metadata → maven-plugin → core → om
12+
```
13+
14+
**Critical**: `metadata` must be built first as it generates models used by `core`.
15+
16+
### Module Responsibilities
17+
18+
#### 1. Metadata Module (`metadata/`)
19+
- **Core metadata models**: `MetaObject`, `MetaField`, `MetaAttribute`
20+
- **Exception hierarchy**: `MetaDataException`, `ValueException`, `InvalidMetaDataException`
21+
- **Base interfaces**: `MetaDataAware`, `DataTypeAware`, `MetaDataValueHandler`
22+
- **Data type system**: `DataTypes` enum, validation framework
23+
- **Key classes**: `MetaAttribute`, `StringAttribute`, `ClassAttribute`
24+
25+
#### 2. Maven Plugin Module (`maven-plugin/`)
26+
- **Code generation**: `MetaDataGeneratorMojo`
27+
- **Build integration**: Maven lifecycle integration
28+
- **Configuration**: `GeneratorParam`, `LoaderParam`
29+
- **MojoSupport**: Interface for MetaDataLoader integration
30+
31+
#### 3. Core Module (`core/`)
32+
- **MetaObject implementations**: `ValueMetaObject`, `DataMetaObject`, `ProxyMetaObject`, `MappedMetaObject`
33+
- **Loader framework**: `FileMetaDataLoader`, `XMLFileMetaDataLoader`
34+
- **IO system**: JSON/XML serialization with Gson integration
35+
- **Generators**: PlantUML, XSD, JSON model generators
36+
- **Validation**: Field and object-level validation framework
37+
38+
#### 4. Object Manager Module (`om/`)
39+
- **Expression system**: `Expression`, `ExpressionGroup`, `ExpressionOperator`
40+
- **Query framework**: `QueryOptions`, `Range`, `SortOrder`
41+
- **Manager integration**: `ManagerAwareMetaObject`
42+
43+
## Key Design Patterns
44+
45+
### 1. Metadata-Driven Architecture
46+
```java
47+
// Objects are defined by metadata, not classes
48+
MetaObject metaObj = loader.getMetaObject("MyObject");
49+
Object instance = metaObj.newInstance();
50+
metaObj.setFieldValue(instance, "fieldName", value);
51+
```
52+
53+
### 2. Type System
54+
```java
55+
public enum DataTypes {
56+
STRING, INT, LONG, FLOAT, DOUBLE, BOOLEAN, DATE, OBJECT, ARRAY
57+
}
58+
```
59+
60+
### 3. MetaObject Inheritance Hierarchy
61+
```
62+
MetaDataAware
63+
├── MetaObject (interface)
64+
├── ValueMetaObject (dynamic, public access)
65+
├── DataMetaObject (wrapped, protected access)
66+
├── ProxyMetaObject (proxy implementations)
67+
└── MappedMetaObject (Map-based objects)
68+
```
69+
70+
### 4. Loader Architecture
71+
```
72+
MetaDataLoader (base)
73+
├── FileMetaDataLoader (sophisticated parser)
74+
├── XMLFileMetaDataLoader (backward compatible)
75+
└── SimpleLoader (strict TypesConfig/MetaModel)
76+
```
77+
78+
## Critical Components
79+
80+
### MetaObject Interface
81+
- `newInstance()` - Create objects from metadata
82+
- `getFieldValue()/setFieldValue()` - Field access
83+
- `performValidation()` - Object validation
84+
- `getMetaField()` - Field metadata access
85+
86+
### Serialization System
87+
- **JsonModelWriter/JsonMetaDataWriter**: Gson-based JSON serialization
88+
- **XMLSerializationHandler**: Custom XML serialization
89+
- **TypeAdapters**: MetaObject-aware Gson adapters
90+
91+
### Validation Framework
92+
- **Field-level**: `ArrayValidator`, `StringValidator`
93+
- **Object-level**: `MetaValidator` interface
94+
- **Integration**: Automatic validation on object creation/modification
95+
96+
### Generator Framework
97+
- **PlantUML**: UML diagram generation from metadata
98+
- **XSD**: Schema generation for MetaModel files
99+
- **JSON Models**: Export metadata as JSON
100+
- **Code Generation**: Java interface generation
101+
102+
## Data Flow
103+
104+
### 1. Metadata Loading
105+
```
106+
TypesConfig.xml → MetaDataLoader → MetaObject definitions → Registry
107+
```
108+
109+
### 2. Object Creation
110+
```
111+
MetaObject.newInstance() → Apply defaults → Validation → Object instance
112+
```
113+
114+
### 3. Serialization
115+
```
116+
Object → MetaObject → TypeAdapter → JSON/XML output
117+
```
118+
119+
## Configuration Files
120+
121+
### TypesConfig.xml
122+
Defines metadata structure, validation rules, and object relationships:
123+
```xml
124+
<typesConfig>
125+
<metaObjects>
126+
<object name="Person" class="com.example.Person">
127+
<field name="name" type="STRING" required="true"/>
128+
<field name="age" type="INT" defaultValue="0"/>
129+
</object>
130+
</metaObjects>
131+
</typesConfig>
132+
```
133+
134+
### MetaModel Files
135+
Define specific object instances and their metadata.
136+
137+
## Performance Considerations
138+
139+
### Caching Strategy
140+
- **ArrayValidator**: Caches min/max size values with boolean flags
141+
- **MetaObject Registry**: Singleton pattern for metadata caching
142+
- **Type conversion**: Optimized paths for native types
143+
144+
### Memory Management
145+
- Uses modern Java features (Java 21)
146+
- StringBuilder over StringBuffer for performance
147+
- Lazy loading of metadata where possible
148+
149+
## Error Handling Patterns
150+
151+
### Exception Hierarchy
152+
```
153+
MetaException (base)
154+
├── MetaDataException
155+
│ ├── MetaDataNotFoundException
156+
│ └── InvalidMetaDataException
157+
└── ValueException
158+
├── ValueNotFoundException
159+
└── InvalidValueException
160+
```
161+
162+
### Error Recovery
163+
- Graceful fallbacks in parsers
164+
- Comprehensive logging with SLF4J
165+
- Validation with detailed error messages
166+
167+
## Integration Points
168+
169+
### Maven Integration
170+
- Build-time code generation
171+
- Classpath-aware loading (runtime/compile/test)
172+
- OSGi bundle generation
173+
174+
### Spring Boot Compatibility
175+
- Gson-based JSON serialization works with Spring Boot
176+
- Replace Jackson with Gson for MetaObject support
177+
178+
### OSGi Support
179+
- Full OSGi bundle metadata
180+
- Classloader-aware metadata loading
181+
- Dynamic package imports/exports
182+
183+
## Development Guidelines
184+
185+
### Adding New MetaObject Types
186+
1. Extend base MetaObject interface
187+
2. Implement required lifecycle methods
188+
3. Add serialization support
189+
4. Update validation framework
190+
5. Add comprehensive tests
191+
192+
### Creating New Generators
193+
1. Implement Generator interface
194+
2. Register in plugin configuration
195+
3. Add Maven goal support
196+
4. Document output format
197+
198+
### Extending Validation
199+
1. Create validator implementing appropriate interface
200+
2. Register in metadata configuration
201+
3. Add to validation chain
202+
4. Test edge cases thoroughly
203+
204+
## Common Pitfalls
205+
206+
1. **Build Order**: Always build `metadata` before `core`
207+
2. **Classloader Issues**: Set appropriate classloader for OSGi/Maven contexts
208+
3. **Validation**: Don't skip object-level validation
209+
4. **Serialization**: Use MetaObject-aware serializers for complex objects
210+
5. **Memory**: Be careful with metadata caching in long-running applications
211+
212+
## Future Architecture (v4.4.0+)
213+
214+
- **Abstract/Interface MetaData**: Native support for inheritance
215+
- **Enhanced IO**: YAML, HOCON, TOML support
216+
- **Plugin Architecture**: Extensible IO readers/writers
217+
- **Editor Integration**: GUI-based metadata editing
218+
- **Advanced TypedMetaDataLoader**: More sophisticated loading control

0 commit comments

Comments
 (0)