Domain Models Documentation Index

Last Updated: September 18, 2025 Status: ✅ Complete and Current - MIGRATED TO HUB-AND-SPOKE ARCHITECTURE

🚀 NEW LOCATION - Hub-and-Spoke Architecture

📋 Models Architecture Hub

Primary Entry Point - Complete navigation hub for all 38 domain models with hub-and-spoke architecture.

New Structure:

• Hub Document: models-architecture.md - Navigation and summaries
• Pure Domain: models/pure-domain.md - 8 core business models
• Supporting Domain: models/supporting-domain.md - 7 business models with data structures
• Integration & Transfer: models/integration.md - 16 external system models
• Infrastructure: models/infrastructure.md - 8 system operation models

Migration Benefits:

• All 39 models now documented (vs. previous 20)
• Organized by architectural layers with DDD purity warnings
• Multiple navigation paths: technical, functional, alphabetical
• Manageable file sizes with complete field definitions
• Cross-references and relationships fully mapped

Supporting Documentation

🔧 Schema Validator (PM-056)

Validation Tool - Automated tool for preventing domain/database model drift.

Contains:

• Field validation and type compatibility checking
• Enum validation and relationship detection
• Current status and known issues
• Usage instructions and CI/CD integration

📝 Domain Model Updates (July 31, 2025)

Change Log - Detailed record of recent domain model improvements.

Contains:

• Complete field additions summary (26 fields)
• Relationship improvements (9 fields)
• Validation results and success metrics
• Next steps for Code team
• Architectural impact analysis

🔗 Quick Access to New Architecture

By Technical Layer

• Pure Domain Models - Core business concepts (8 models)
• Supporting Domain Models - Business with data structures (7 models)
• Integration Models - External system contracts (16 models)
• Infrastructure Models - System mechanisms (8 models)

By Business Function

• #pm - Product Management (12 models)
• #workflow - Process Orchestration (5 models)
• #knowledge - Information Management (9 models)
• #spatial - Spatial Intelligence (5 models)

Core Models (New Locations)

• Product - Products being managed
• Feature - Features or capabilities
• WorkItem - Universal work items
• Workflow - Workflow definition and state
• Task - Individual tasks within workflows
• Intent - User intent parsed from natural language

Project Management (New Locations)

• Project - PM projects with integrations
• ProjectIntegration - Integration configurations

Infrastructure Models (New Locations)

• Event - Base event class
• List - Universal lists
• Todo - Task management
• Conversation - User-AI conversations

Recent Updates Summary

September 18, 2025 - Hub-and-Spoke Migration

• Hub-and-spoke architecture implemented - All 39 models organized by technical layers
• 19 new models documented that were previously undocumented
• Field accuracy verified against actual services/domain/models.py source
• Multiple navigation paths - By layer, function, and alphabetical
• DDD purity warnings added for clear architectural boundaries
• Cross-references completed between all models and layers

July 31, 2025 - Major Field Additions (Previous Update)

• 26 fields added across 7 models
• 9 relationship fields for database alignment
• Complete schema alignment achieved
• All imports working correctly

Models Updated

1. Task (6 fields) - Timing and data flow support
2. WorkItem (5 fields) - Feature and product associations
3. Workflow (4 fields) - State tracking and data flow
4. Feature (2 fields) - Product association and work items
5. Intent (2 fields) - Workflow association
6. Product (1 field) - Work items relationship
7. ProjectIntegration (1 field) - Project relationship

Current Status

✅ Completed

• All domain model field additions
• Relationship consistency improvements
• Documentation consolidation
• Import validation

🔄 Pending (Code Team)

• SQLAlchemy metadata conflict resolution
• Database field additions
• Schema validator fixes

Usage

For Developers

1. Start with Models Architecture Hub for complete model information
2. Check Schema Validator for validation status
3. Review Recent Updates for latest changes

For Code Team

1. Review Domain Model Updates for next steps
2. Address SQLAlchemy metadata conflict in database models
3. Add missing database fields for complete alignment

For Architecture Reviews

1. Examine Models Architecture Hub for architectural principles
2. Validate against Schema Validator
3. Consider impact of recent changes in Updates

File Structure

docs/architecture/
├── domain-models-index.md          # This file - Single entry point
├── domain-models.md                # Main reference document
└── ...

docs/tools/
└── PM-056-schema-validator.md      # Validation tool documentation

docs/development/
└── domain-model-updates-2025-07-31.md  # Recent changes log

Maintenance

When Adding New Models

1. Update Models Architecture Hub and appropriate spoke document
2. Add to Quick Access section in this index
3. Update schema validator if needed
4. Document changes in development log

When Modifying Existing Models

1. Update Models Architecture Hub and appropriate spoke document
2. Run schema validation
3. Document changes in development log
4. Update this index if structure changes

When Updating Documentation

1. Keep this index as the single entry point
2. Maintain cross-references between documents
3. Update “Last Updated” timestamps
4. Ensure all links remain valid

Single Source of Truth: All domain model documentation is accessible through this index file.

Status: ✅ CURRENT - Complete and consolidated domain model documentation