DOCS: Reorganize Documentation into .claude Directory Structure

* Streamlined active Claude Code context by moving documentation to .claude/
* Created archive/ subdirectory for historical content accessible on request
* Consolidated CLAUDE.md and CLAUDE_ARCHITECTURE.md into streamlined main guide
* Preserved architectural-summary.md as separate quick reference for anti-patterns
* Updated all internal documentation references to new archive locations
* Updated source code comments in codegen/ module to reference archived files
* Maintained version management and command references in active context
* Removed temporary test files and outdated documentation

Structure:
- .claude/CLAUDE.md - Streamlined main guide (current v6.0.0+ focus)
- .claude/architectural-summary.md - Critical quick reference & anti-patterns
- .claude/archive/ - Historical analysis and completed implementation summaries
- .claude/react-metaview-system.md - Current React implementation reference

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: dmealing

.claude/CLAUDE.md

@@ -0,0 +1,276 @@
+# MetaObjects Project - Claude AI Assistant Guide
+
+## ⚠️ CRITICAL ARCHITECTURAL PRINCIPLE ⚠️
+
+**MetaObjects follows a LOAD-ONCE IMMUTABLE design pattern analogous to Java's Class/Field reflection system:**
+
+- **MetaData objects are loaded once during application startup and remain immutable thereafter**
+- **They are permanent in memory for the application lifetime (like Java Class objects)**
+- **Thread-safe for concurrent READ operations after loading phase**
+- **DO NOT treat MetaData as mutable domain objects - they are immutable metadata definitions**
+
+### Framework Analogy
+| Java Reflection | MetaObjects Framework |
+|----------------|----------------------|
+| `Class.forName()` | `MetaDataLoader.load()` |
+| `Class.getFields()` | `MetaObject.getMetaFields()` |
+| `Field.get(object)` | `MetaField.getValue(object)` |
+| Permanent in memory | Permanent MetaData objects |
+| Thread-safe reads | Thread-safe metadata access |
+| ClassLoader registry | MetaDataTypeRegistry |
+
+## Project Overview
+
+MetaObjects is a Java-based suite of tools for metadata-driven development, providing sophisticated control over applications beyond traditional model-driven development techniques.
+
+- **Current Version**: 5.2.0 (development) 
+- **Java Version**: Java 21
+- **Build Tool**: Maven
+- **License**: Apache License 2.0
+
+## Current Architecture (v6.0.0+)
+
+### Service-Based Type Registry
+- **MetaDataTypeRegistry**: Service-based type registry (replaces TypesConfig)
+- **MetaDataEnhancementService**: Context-aware metadata enhancement
+- **ServiceLoader Discovery**: OSGI-compatible service discovery
+- **Cross-Language Ready**: String-based types work across Java/C#/TypeScript
+
+### Project Structure
+```
+├── metadata/           # Base metadata models and types
+├── codegen/           # Code generation libraries (v6.0.0+)
+├── maven-plugin/      # Maven plugin for code generation
+├── core/              # Core MetaObjects functionality  
+├── om/                # Object Manager module
+├── omdb/              # Database Object Manager
+├── omnosql/           # NoSQL Object Manager
+├── web/               # React MetaView components
+├── demo/              # Demo applications with React integration
+└── docs/              # Documentation
+```
+
+### Build Dependencies (CRITICAL ORDER)
+```
+metadata → codegen → maven-plugin → core → om → omdb/omnosql → web → demo
+```
+
+**Build the project**: `mvn clean compile`
+
+## Core Concepts
+
+### MetaObjects Types
+- **ValueMetaObject**: Dynamic objects with public getter/setter access
+- **DataMetaObject**: Wrapped objects with protected access + Builder patterns
+- **ProxyMetaObject**: Proxy implementations without concrete classes
+- **MappedMetaObject**: Works with Map interface objects
+
+### Key Features
+- **Metadata-driven development** with sophisticated control mechanisms
+- **Cross-language code generation** (Java, C#, TypeScript)
+- **JSON/XML serialization** with custom type adapters
+- **Validation framework** with field-level and object-level validators
+- **React MetaView System** with TypeScript components
+- **Enhanced error reporting** with hierarchical paths and context
+
+## Current Service Architecture Patterns
+
+### MetaDataTypeRegistry Usage
+```java
+// v6.0.0+ pattern - service-based type registry
+MetaDataTypeRegistry registry = ServiceRegistry.getInstance()
+    .getService(MetaDataTypeRegistry.class);
+    
+// Register custom types
+registry.registerType("customField", CustomField.class);
+```
+
+### MetaDataEnhancement Usage  
+```java
+// Attribute enhancement for cross-cutting concerns
+MetaDataEnhancementService enhancer = new MetaDataEnhancementService();
+for (MetaObject metaObject : loader.getChildren(MetaObject.class)) {
+    enhancer.enhanceForService(metaObject, "objectManagerDB", 
+        Map.of("dialect", "postgresql", "schema", "public"));
+}
+// Objects now have dbTable, dbCol, dbNullable attributes
+```
+
+### Modern API Patterns
+```java
+// Optional-based APIs (v5.1.0+)
+Optional<String> name = metaObject.findString("name");
+String email = metaObject.requireString("email"); // throws if missing
+
+// Builder patterns
+ValueObject obj = ValueObject.builder()
+    .field("name", "John")
+    .field("age", 30)
+    .build();
+
+// Stream APIs
+metaObject.getFieldsStream()
+    .filter(field -> field.getType() == DataTypes.STRING)
+    .forEach(field -> processField(field));
+```
+
+## React MetaView Integration
+
+### Backend API Pattern
+```java
+// Spring REST controllers serve metadata as JSON
+@RestController
+public class MetaDataApiController {
+    
+    @GetMapping("/api/metadata/{objectName}")
+    public ResponseEntity<String> getMetaObjectJson(@PathVariable String objectName) {
+        MetaObject metaObject = loader.getMetaObject(objectName);
+        return ResponseEntity.ok(JsonObjectWriter.write(metaObject));
+    }
+}
+```
+
+### Frontend Component Pattern
+```typescript
+// TypeScript MetaView components
+import { MetaViewRenderer } from './components/metaviews/MetaViewRenderer';
+import { MetaObjectForm } from './components/forms/MetaObjectForm';
+
+// Automatic form generation from metadata
+<MetaObjectForm 
+    metaObjectName="User"
+    onSubmit={handleSubmit}
+    validation={true}
+/>
+```
+
+### JSON Metadata Location
+- Place JSON metadata in `/src/main/resources/metadata/` for proper classpath loading
+- Use FileMetaDataLoader with JsonMetaDataParser for existing infrastructure
+
+## Development Guidelines
+
+### Code Style & Patterns
+- Use **SLF4J** for all logging (migrated from Commons Logging)
+- Follow **Builder patterns** for complex object creation
+- Use **Optional-based APIs** for safe null handling
+- Maintain **backward compatibility** in all changes
+- Add **comprehensive JavaDoc** for public APIs
+
+### Testing
+- Use **JUnit 4.13.2** for testing
+- All modules must compile successfully with Java 21
+- Test files should follow existing patterns in `*/src/test/java/`
+
+### Module Integration
+- **codegen module**: Contains all code generation functionality
+- **web module**: React TypeScript components and generic Spring controllers  
+- **demo module**: Fishstore demo, data controllers, and JSON metadata
+- **Controllers**: Demo-specific controllers → demo module, generic → web module
+
+### React & Frontend Development
+- **Use Existing Infrastructure**: Leverage FileMetaDataLoader, JsonObjectWriter from IO package
+- **Spring Integration**: Proper controller module placement based on functionality
+- **TypeScript Components**: Follow React MetaView patterns for metadata-driven UI
+- **State Management**: Redux Toolkit with React Query for form state and data fetching
+
+## Enhanced Error Reporting (v5.2.0+)
+
+### Rich Exception Context
+```java
+try {
+    // MetaObjects operation
+} catch (MetaDataException e) {
+    Optional<MetaDataPath> path = e.getMetaDataPath();
+    Optional<String> operation = e.getOperation();
+    Map<String, Object> context = e.getContext();
+    
+    // Enhanced error messages include context and alternatives
+    // "Field 'invalidField' not found in User: Available: age, email, name"
+}
+```
+
+### Factory Method Patterns
+```java
+// Context-rich exception creation
+ObjectNotFoundException.forId(userId, metaObject, "userLookup");
+PersistenceException.forSave(entity, metaObject, sqlException);
+GeneratorException.forTemplate("user.java.vm", metaObject, templateException);
+```
+
+## Key Build Commands
+
+```bash
+# Build entire project
+mvn clean compile
+
+# Run tests
+mvn test
+
+# Package project
+mvn package
+
+# Generate code using MetaObjects plugin
+mvn metaobjects:generate
+
+# Build specific module (respects dependency order)
+cd metadata && mvn compile
+cd core && mvn compile
+```
+
+## Maven Configuration
+- Parent POM manages dependency versions
+- OSGi bundle support enabled via Apache Felix Maven Bundle Plugin
+- Java 21 compatibility with --release flag
+- Two distribution profiles: default (Draagon) and nexus (Maven Central)
+
+## Critical Files for Development
+
+### Source Code
+- Core source: `core/src/main/java/com/draagon/meta/`
+- Metadata models: `metadata/src/main/java/com/draagon/meta/`
+- Tests: `*/src/test/java/`
+
+### React MetaView System
+- React components: `web/src/typescript/components/metaviews/`
+- React forms: `web/src/typescript/components/forms/`
+- TypeScript types: `web/src/typescript/types/metadata.ts`
+- Spring controllers: `web/src/main/java/com/draagon/meta/web/react/api/`
+- Demo controllers: `demo/src/main/java/com/draagon/meta/demo/fishstore/api/`
+- JSON metadata: `demo/src/main/resources/metadata/fishstore-metadata.json`
+
+### Configuration
+- `pom.xml` - Main project configuration
+- `package.json` & `tsconfig.json` - React/TypeScript configuration (web module)
+- `README.md` - Basic project information
+- `RELEASE_NOTES.md` - Version history
+
+## Key Technologies & Dependencies
+
+- **Java 21** with Maven compiler plugin 3.13.0
+- **SLF4J + Logback** for logging
+- **JUnit 4.13.2** for testing
+- **OSGi Bundle Support** via Apache Felix Maven Bundle Plugin
+- **Gson 2.13.1** for JSON handling
+- **Commons Validator 1.9.0** for validation
+- **React + TypeScript** for frontend components
+- **Redux Toolkit** for state management
+
+## VERSION MANAGEMENT FOR CLAUDE AI
+
+**CRITICAL**: When user requests "increment version", "update version", or "release new version":
+
+1. **AUTOMATICALLY UPDATE ALL VERSION REFERENCES**:
+   - All pom.xml files (root + 8 modules)
+   - README.md "Current Release:" line  
+   - RELEASE_NOTES.md (add new version section)
+   - This CLAUDE.md version references
+
+2. **FOLLOW VERSION STRATEGY**:
+   - Release: Remove -SNAPSHOT from current version
+   - Next Dev: Increment version + add -SNAPSHOT
+   - Ensure ALL modules have identical versions
+
+3. **VERIFY BUILD**: Run `mvn clean compile` after changes
+
+This ensures complete version synchronization across the entire project when versions are updated.

CLAUDE_COMMANDS.md .claude/CLAUDE_COMMANDS.mdCLAUDE_COMMANDS.md renamed to .claude/CLAUDE_COMMANDS.md

@@ -72,7 +72,7 @@ Release date: [Current Date]
 ```
 
 ### Step 5: Update CLAUDE.md
-Located at: `./CLAUDE.md`
+Located at: `./.claude/CLAUDE.md`
 
 Update lines:
 - Line 6: `- **Current Version**: X.Y.Z-SNAPSHOT (latest stable: X.Y.Z)`
@@ -84,7 +84,7 @@ Search and verify these files/patterns are updated:
 - All pom.xml files contain new version
 - README.md shows new current release
 - RELEASE_NOTES.md has new version section
-- CLAUDE.md reflects new version
+- .claude/CLAUDE.md reflects new version
 - Any hardcoded version references in documentation
 
 ## Files That Must Be Updated
@@ -97,7 +97,7 @@ Search and verify these files/patterns are updated:
 5. **./om/pom.xml** - Object Manager module version
 6. **./README.md** - Current Release line
 7. **./RELEASE_NOTES.md** - Add new version section
-8. **./CLAUDE.md** - Current version and recent changes header
+8. **./.claude/CLAUDE.md** - Current version and recent changes header
 
 ### Secondary Files (Update if uncommented in build)
 9. **./demo/pom.xml** - Demo module version
@@ -118,7 +118,7 @@ When user requests version increment:
 # 1. Update all POM files with new version
 # 2. Update README.md current release
 # 3. Update RELEASE_NOTES.md with new section
-# 4. Update CLAUDE.md version references
+# 4. Update .claude/CLAUDE.md version references
 # 5. Verify all changes with grep search
 # 6. Build and test the project
 mvn clean compile
@@ -167,7 +167,7 @@ grep "Current Release:" README.md
 head -20 RELEASE_NOTES.md | grep "Version"
 
 # Verify CLAUDE.md version
-grep "Current Version" CLAUDE.md
+grep "Current Version" .claude/CLAUDE.md
 ```
 
 ## Error Prevention
@@ -176,15 +176,15 @@ grep "Current Version" CLAUDE.md
 1. **Version Consistency**: All pom.xml files MUST have same version
 2. **SNAPSHOT Handling**: Development versions should end with -SNAPSHOT
 3. **Date Updates**: RELEASE_NOTES.md should have current date
-4. **Section Headers**: Update major changes section in CLAUDE.md
+4. **Section Headers**: Update major changes section in .claude/CLAUDE.md
 5. **Build Verification**: Project must compile after version changes
 
 ### Common Mistakes to Avoid
 1. Forgetting to update child module versions
 2. Missing README.md current release update
 3. Not adding new section to RELEASE_NOTES.md
 4. Inconsistent version numbers across modules
-5. Forgetting to update CLAUDE.md version references
+5. Forgetting to update .claude/CLAUDE.md version references
 
 ## Implementation Notes for Claude AI
 

CLAUDE_VERSION_MANAGEMENT.md .claude/CLAUDE_VERSION_MANAGEMENT.mdCLAUDE_VERSION_MANAGEMENT.md renamed to .claude/CLAUDE_VERSION_MANAGEMENT.md

@@ -483,9 +483,9 @@ Critical metadata overlay functionality restoration that was broken during the v
 
 ## Quick Reference Files
 
-- **Comprehensive Analysis**: `CLAUDE_ARCHITECTURAL_ANALYSIS.md`
-- **Detailed Enhancements**: `CLAUDE_ENHANCEMENTS.md`  
-- **Architecture Guide**: `CLAUDE_ARCHITECTURE.md`
-- **This Summary**: `CLAUDE_ARCHITECTURAL_SUMMARY.md`
+- **Comprehensive Analysis**: `archive/architectural-analysis/CLAUDE_ARCHITECTURAL_ANALYSIS.md`
+- **Detailed Enhancements**: `archive/architectural-analysis/CLAUDE_ENHANCEMENTS.md`  
+- **Architecture Guide**: `archive/architectural-analysis/original-architecture-guide.md`
+- **This Summary**: `architectural-summary.md` (current file)
 
 This framework deserves enhancement, not replacement. The core design is sophisticated and follows metadata framework best practices.