feat: Complete ERD generation system with package migration

🚀 Major Features Implemented:
- Automatic Mermaid ERD generation from SQLModel definitions
- Bidirectional relationship deduplication for clean diagrams
- Comprehensive validation system with syntax checking
- CLI interface for ERD generation and management
- Performance-optimized generation (<30 seconds for 20 tables)

📦 Package Migration:
- Moved all ERD code to dedicated backend/erd package
- Renamed files to remove erd_ prefix (now in erd package)
- Updated all imports across 17+ files
- Reorganized test structure under tests/unit/erd_tests/

🔧 Production Optimization:
- Updated .dockerignore to exclude ERD package from production builds
- Clean separation between core app and documentation tools
- ERD functionality can be excluded from production deployments

🧪 Testing & Quality:
- Comprehensive unit tests for all ERD components
- Performance tests ensuring <30 second generation time
- Integration tests for complete workflows
- Contract tests for CLI interface validation

📚 Documentation & Governance:
- Updated constitution with ERD requirements and performance standards
- Enhanced plan and tasks templates with ERD checks
- Complete ERD documentation with usage examples
- Generated sample ERD diagram (docs/database/erd.mmd)

✅ All Phase 3.5 tasks completed:
- T023-T025: Unit tests for ERD Generator, Model Metadata, validation
- T026: Performance tests (<30 seconds for large schemas)
- T027: Documentation updates
- T028: Constitution updates with ERD requirements
- T029-T030: Template updates with ERD checks
- T031: Code optimization and deduplication
- T032: Manual validation testing

The ERD system is now production-ready with clean architecture,
comprehensive testing, and optimized deployment configuration.

Author: cemmurphy

.cursor/rules/specify-rules.mdc

@@ -0,0 +1,25 @@
+# full-stack-fastapi-template Development Guidelines
+
+Auto-generated from all feature plans. Last updated: 2025-10-03
+
+## Active Technologies
+- Python 3.11+ + SQLModel, Mermaid, Git hooks, pre-commit framework (001-as-a-first)
+
+## Project Structure
+```
+backend/
+frontend/
+tests/
+```
+
+## Commands
+cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] pytest [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] ruff check .
+
+## Code Style
+Python 3.11+: Follow standard conventions
+
+## Recent Changes
+- 001-as-a-first: Added Python 3.11+ + SQLModel, Mermaid, Git hooks, pre-commit framework
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

.pre-commit-config.yaml

@@ -32,6 +32,17 @@ repos:
         language: system
         types: [text]
         files: ^frontend/
+      - id: erd-generation
+        name: ERD generation
+        entry: bash -c 'cd backend && python scripts/generate_erd.py --validate --verbose --force'
+        language: system
+        types: [python]
+        files: ^backend/app/.*\.py$
+        stages: [pre-commit]
+        always_run: false
+        pass_filenames: true
+        require_serial: false
+        description: "Generate and validate ERD diagrams from SQLModel definitions (Mermaid format)"
 
 ci:
   autofix_commit_msg: 🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

.specify/memory/constitution.md

@@ -43,12 +43,16 @@ All new features MUST implement secure defaults: JWT authentication, password ha
 - Integration tests MUST verify API endpoints and database interactions
 - End-to-end tests MUST validate complete user workflows
 - Contract tests MUST ensure API schema consistency
+- ERD generation MUST have unit tests, integration tests, and performance tests
+- ERD validation MUST include syntax validation and relationship verification
 
 ### Documentation Standards
 - All new features MUST include API documentation via OpenAPI/Swagger
 - User-facing features MUST have updated README sections
 - Complex business logic MUST include inline documentation
 - Deployment changes MUST update deployment.md
+- Database schema changes MUST automatically update Entity Relationship Diagrams (ERD)
+- ERD documentation MUST be generated from SQLModel definitions and kept in sync
 
 ## Quality Standards
 
@@ -57,6 +61,7 @@ All new features MUST implement secure defaults: JWT authentication, password ha
 - Frontend pages MUST load within 2 seconds
 - Database queries MUST be optimized and indexed appropriately
 - Docker containers MUST start within 30 seconds
+- ERD generation MUST complete within 30 seconds for schemas with up to 20 tables and 100 fields
 
 ### Accessibility Standards
 - All UI components MUST meet WCAG 2.1 AA standards

.specify/templates/plan-template.md

@@ -52,6 +52,7 @@
 **Auto-Generated Client**: Will API changes require frontend client regeneration?
 **Docker-First**: Does the feature work in containerized environment?
 **Security by Default**: Are authentication, validation, and security considerations included?
+**ERD Documentation**: Will database schema changes require ERD updates and validation?
 
 ## Project Structure
 

.specify/templates/tasks-template.md

@@ -73,8 +73,9 @@
 - [ ] T019 [P] Unit tests for validation in tests/unit/test_validation.py
 - [ ] T020 Performance tests (<200ms)
 - [ ] T021 [P] Update docs/api.md
-- [ ] T022 Remove duplication
-- [ ] T023 Run manual-testing.md
+- [ ] T022 [P] Update ERD documentation if database schema changed
+- [ ] T023 Remove duplication
+- [ ] T024 Run manual-testing.md
 
 ## Dependencies
 - Tests (T004-T007) before implementation (T008-T014)
@@ -124,4 +125,5 @@ Task: "Integration test auth in tests/integration/test_auth.py"
 - [ ] All tests come before implementation
 - [ ] Parallel tasks truly independent
 - [ ] Each task specifies exact file path
-- [ ] No task modifies same file as another [P] task
+- [ ] No task modifies same file as another [P] task
+- [ ] ERD documentation tasks included if database schema changes

backend/.dockerignore

@@ -6,3 +6,10 @@ app.egg-info
 .coverage
 htmlcov
 .venv
+
+# ERD Package (development/documentation only)
+erd/
+scripts/generate_erd.py
+tests/unit/erd_tests/
+tests/performance/test_erd_*.py
+tests/integration/test_erd_*.py

backend/erd/__init__.py

@@ -0,0 +1,63 @@
+"""
+ERD Package - Entity Relationship Diagram generation from SQLModel definitions.
+
+This package provides functionality to automatically generate Mermaid ERD diagrams
+from SQLModel class definitions, including validation and output formatting.
+
+Main Components:
+- generator: Main ERD generation logic
+- models: Data structures for model metadata
+- validation: ERD validation and error checking
+- discovery: SQLModel introspection and parsing
+- output: ERD output formatting and file handling
+- entities: Entity definition structures
+- fields: Field definition structures
+- relationships: Relationship definition and management
+- mermaid_validator: Mermaid syntax validation
+
+Usage:
+    from erd import ERDGenerator
+    
+    generator = ERDGenerator()
+    mermaid_code = generator.generate_erd()
+"""
+
+from .generator import ERDGenerator
+from .models import (
+    FieldMetadata,
+    ModelMetadata, 
+    RelationshipMetadata,
+    ConstraintMetadata
+)
+from .validation import (
+    ERDValidator,
+    ValidationResult,
+    ValidationError,
+    ErrorSeverity,
+    ValidationMode
+)
+from .output import ERDOutput
+from .entities import EntityDefinition
+from .relationships import RelationshipDefinition, RelationshipManager
+from .discovery import ModelDiscovery
+from .mermaid_validator import MermaidValidator
+
+__version__ = "1.0.0"
+__all__ = [
+    "ERDGenerator",
+    "FieldMetadata",
+    "ModelMetadata", 
+    "RelationshipMetadata",
+    "ConstraintMetadata",
+    "ERDValidator",
+    "ValidationResult",
+    "ValidationError",
+    "ErrorSeverity",
+    "ValidationMode",
+    "ERDOutput",
+    "EntityDefinition",
+    "RelationshipDefinition",
+    "RelationshipManager",
+    "ModelDiscovery",
+    "MermaidValidator",
+]