Initial commit
This commit is contained in:
Zhongwei Li
43
skills/ontological-documentation/reference/INDEX.md
Normal file
43
skills/ontological-documentation/reference/INDEX.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Ontological Documentation Reference
|
||||
|
||||
Technical reference for creating ontological documentation of Grey Haven systems.
|
||||
|
||||
## Reference Materials
|
||||
|
||||
1. **[Concept Extraction Guide](concept_extraction_guide.md)** - How to extract concepts from code
|
||||
- TanStack Start extraction patterns
|
||||
- FastAPI extraction patterns
|
||||
- Identifying entities and relationships
|
||||
- Semantic analysis techniques
|
||||
|
||||
2. **[Ontology Patterns](ontology_patterns.md)** - Common Grey Haven patterns
|
||||
- Multi-tenant patterns
|
||||
- Repository pattern
|
||||
- Service layer patterns
|
||||
- Authentication patterns
|
||||
- Database conventions
|
||||
|
||||
3. **[Documentation Templates](documentation_templates.md)** - Template formats
|
||||
- Entity documentation
|
||||
- Relationship diagrams
|
||||
- Architecture overviews
|
||||
- Domain model templates
|
||||
|
||||
4. **[Visualization Techniques](visualization-techniques.md)** - Diagram creation
|
||||
- Mermaid diagrams
|
||||
- Entity-relationship diagrams
|
||||
- Component hierarchies
|
||||
- Data flow diagrams
|
||||
|
||||
## Quick Links
|
||||
|
||||
- For examples: See [examples/](../examples/INDEX.md)
|
||||
- For templates: See [templates/](../templates/)
|
||||
- For scripts: See [scripts/](../scripts/)
|
||||
- For checklists: See [checklists/](../checklists/)
|
||||
|
||||
---
|
||||
|
||||
**Coverage**: Concept extraction, Patterns, Templates, Visualization
|
||||
**Platforms**: TanStack Start, FastAPI
|
||||
**Last Updated**: 2025-11-09
|
||||
55
skills/ontological-documentation/reference/README.md
Normal file
55
skills/ontological-documentation/reference/README.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# Reference Guides
|
||||
|
||||
This directory contains comprehensive reference guides for ontological documentation.
|
||||
|
||||
## Files
|
||||
|
||||
### concept_extraction_guide.md
|
||||
Methodologies and techniques for identifying and extracting domain concepts, entities, and relationships from software codebases.
|
||||
|
||||
**Topics covered:**
|
||||
- Static code analysis techniques
|
||||
- Naming convention analysis
|
||||
- Data structure analysis
|
||||
- Configuration and metadata analysis
|
||||
- Language-specific extraction patterns (Python, JavaScript/TypeScript, Java)
|
||||
- Concept categorization framework
|
||||
- Relationship identification
|
||||
- Extraction workflow
|
||||
- Quality assurance
|
||||
|
||||
### documentation_templates.md
|
||||
Standardized templates for creating comprehensive ontological documentation.
|
||||
|
||||
**Templates included:**
|
||||
- Concept Definition Template
|
||||
- Relationship Documentation Template
|
||||
- Domain Model Overview Template
|
||||
- Ontology Change Log Template
|
||||
- API Ontology Template
|
||||
- Database Schema Ontology Template
|
||||
- Event-Driven Architecture Ontology Template
|
||||
|
||||
### ontology_patterns.md
|
||||
Common ontological patterns and taxonomies found in software systems.
|
||||
|
||||
**Patterns covered:**
|
||||
- Fundamental relationship types (Is-A, Part-Of, Instance-Of, Depends-On, Associates-With)
|
||||
- Layered Architecture Pattern
|
||||
- Domain-Driven Design Pattern
|
||||
- MVC Pattern Ontology
|
||||
- Microservices Pattern Ontology
|
||||
- Taxonomy classification systems
|
||||
- Ontology validation rules
|
||||
|
||||
## Usage
|
||||
|
||||
These guides are designed to be used together:
|
||||
|
||||
1. Start with **ontology_patterns.md** to understand common patterns
|
||||
2. Use **concept_extraction_guide.md** to extract concepts from your codebase
|
||||
3. Apply **documentation_templates.md** to document your findings
|
||||
|
||||
## Integration with Main Skill
|
||||
|
||||
These references support the main [SKILL.md](../SKILL.md) and are automatically available when the ontological documentation skill is activated.
|
||||
@@ -0,0 +1,271 @@
|
||||
# Concept Extraction Guide for Software Systems
|
||||
|
||||
This guide provides methodologies and techniques for identifying and extracting domain concepts, entities, and relationships from software codebases to build ontological documentation.
|
||||
|
||||
## Extraction Methodologies
|
||||
|
||||
### 1. Static Code Analysis
|
||||
|
||||
#### Class and Interface Analysis
|
||||
- **Objective**: Identify conceptual entities and their hierarchies
|
||||
- **Sources**: Class definitions, interface declarations, type annotations
|
||||
- **Techniques**:
|
||||
- Parse AST (Abstract Syntax Trees) to find type definitions
|
||||
- Extract inheritance relationships (extends, implements)
|
||||
- Identify composition patterns through member variables
|
||||
- Analyze method signatures for behavioral concepts
|
||||
|
||||
#### Function and Method Analysis
|
||||
- **Objective**: Discover actions, processes, and behavioral concepts
|
||||
- **Sources**: Function definitions, method declarations
|
||||
- **Techniques**:
|
||||
- Group related functions into conceptual categories
|
||||
- Identify command/query patterns (CQRS)
|
||||
- Extract business process flows from method call chains
|
||||
- Map function parameters to conceptual relationships
|
||||
|
||||
#### Import and Dependency Analysis
|
||||
- **Objective**: Understand system boundaries and external dependencies
|
||||
- **Sources**: Import statements, package dependencies, service calls
|
||||
- **Techniques**:
|
||||
- Map module dependencies to conceptual relationships
|
||||
- Identify external system boundaries
|
||||
- Categorize dependencies (internal, external, third-party)
|
||||
- Analyze dependency graphs for architectural insights
|
||||
|
||||
### 2. Naming Convention Analysis
|
||||
|
||||
#### Semantic Naming Patterns
|
||||
- **Entity Nouns**: User, Order, Product, Account (domain objects)
|
||||
- **Process Verbs**: ProcessPayment, ValidateInput, SendEmail (actions)
|
||||
- **State Adjectives**: Active, Pending, Completed, Expired (states)
|
||||
- **Role-based Names**: AdminService, UserGateway, PaymentProcessor (roles)
|
||||
|
||||
#### Naming Pattern Recognition
|
||||
```
|
||||
Entity + Pattern = Concept Type
|
||||
- User + Repository = Data Access Concept
|
||||
- Order + Service = Business Logic Concept
|
||||
- Payment + Gateway = Integration Concept
|
||||
- Notification + Event = Event Concept
|
||||
```
|
||||
|
||||
### 3. Data Structure Analysis
|
||||
|
||||
#### Database Schema Analysis
|
||||
- **Tables as Entities**: Each table represents a domain concept
|
||||
- **Foreign Keys as Relationships**: FKs define relationships between concepts
|
||||
- **Indexes as Properties**: Important attributes for concept identification
|
||||
- **Constraints as Rules**: Business rules and validation logic
|
||||
|
||||
#### API Contract Analysis
|
||||
- **REST Resources**: URL paths often map to domain concepts
|
||||
- **GraphQL Types**: Schema types define conceptual models
|
||||
- **Message Schemas**: Event/message structures reveal concepts
|
||||
- **OpenAPI Specifications**: Complete conceptual model of external interface
|
||||
|
||||
### 4. Configuration and Metadata Analysis
|
||||
|
||||
#### Configuration Files
|
||||
- **Application Settings**: System behavior concepts
|
||||
- **Feature Flags**: Feature-based concept organization
|
||||
- **Environment Variables**: Deployment and environment concepts
|
||||
- **Routing Tables**: Navigation and flow concepts
|
||||
|
||||
#### Documentation and Comments
|
||||
- **README Files**: High-level conceptual overview
|
||||
- **Code Comments**: Designer intent and conceptual explanations
|
||||
- **API Documentation**: External conceptual contracts
|
||||
- **Architecture Diagrams**: Visual conceptual relationships
|
||||
|
||||
## Extraction Techniques by Language
|
||||
|
||||
### Python
|
||||
```python
|
||||
# Key patterns to identify:
|
||||
class UserService: # Service concept
|
||||
def __init__(self, user_repo): # Dependency relationship
|
||||
self.user_repo = user_repo
|
||||
|
||||
def create_user(self, user_dto): # Action concept
|
||||
# Domain logic here
|
||||
pass
|
||||
|
||||
# Look for:
|
||||
# - Class definitions (entities, services, repositories)
|
||||
# - Method names (actions, processes)
|
||||
# - Parameter types (relationships)
|
||||
# - Decorators (cross-cutting concerns)
|
||||
```
|
||||
|
||||
### JavaScript/TypeScript
|
||||
```typescript
|
||||
// Key patterns to identify:
|
||||
interface User { # Entity concept
|
||||
id: string;
|
||||
name: string;
|
||||
}
|
||||
|
||||
class UserService { # Service concept
|
||||
constructor(private userRepo: UserRepository) {} # Dependency
|
||||
|
||||
async createUser(userData: CreateUserDto): Promise<User> { # Action + types
|
||||
// Implementation
|
||||
}
|
||||
}
|
||||
|
||||
// Look for:
|
||||
# - Interface definitions (contracts, entities)
|
||||
# - Class definitions (services, controllers)
|
||||
# - Type annotations (concept properties)
|
||||
# - Decorators (metadata, concerns)
|
||||
```
|
||||
|
||||
### Java
|
||||
```java
|
||||
// Key patterns to identify:
|
||||
@Entity # Entity annotation
|
||||
public class User { # Entity concept
|
||||
@Id
|
||||
private Long id;
|
||||
|
||||
@OneToMany # Relationship annotation
|
||||
private List<Order> orders;
|
||||
}
|
||||
|
||||
@Service # Service annotation
|
||||
public class UserService { # Service concept
|
||||
@Autowired # Dependency injection
|
||||
private UserRepository userRepo;
|
||||
|
||||
public User createUser(UserDto userDto) { // Action + type
|
||||
// Implementation
|
||||
}
|
||||
}
|
||||
|
||||
// Look for:
|
||||
# - Annotations (component types, relationships)
|
||||
# - Class definitions (entities, services)
|
||||
# - Interface definitions (contracts)
|
||||
# - Method signatures (actions, processes)
|
||||
```
|
||||
|
||||
## Concept Categorization Framework
|
||||
|
||||
### Primary Categories
|
||||
|
||||
1. **Domain Entities** (Nouns)
|
||||
- Core business objects: User, Order, Product, Account
|
||||
- Usually persistent, have identity
|
||||
- Contain business logic and state
|
||||
|
||||
2. **Value Objects** (Nouns)
|
||||
- Immutable concepts without identity: Address, Money, DateRange
|
||||
- Defined by their attributes
|
||||
- Often embedded in entities
|
||||
|
||||
3. **Services** (Verb + Noun)
|
||||
- Business logic coordinators: UserService, PaymentService
|
||||
- Stateless operations
|
||||
- Orchestrate domain objects
|
||||
|
||||
4. **Repositories** (Noun + Repository/Store)
|
||||
- Data access abstractions: UserRepository, OrderRepository
|
||||
- Collection-like interfaces
|
||||
- Hide storage details
|
||||
|
||||
5. **Controllers/Handlers** (Noun + Controller/Handler)
|
||||
- Request/response coordination: UserController, OrderController
|
||||
- Interface between external world and domain
|
||||
- Thin layer, delegate to services
|
||||
|
||||
### Secondary Categories
|
||||
|
||||
6. **Events/Notifications** (Past Tense Verbs + Noun)
|
||||
- State changes: OrderCreated, PaymentProcessed, UserRegistered
|
||||
- Asynchronous communication
|
||||
- Decouple system components
|
||||
|
||||
7. **DTOs/Models** (Noun + Dto/Model)
|
||||
- Data transfer objects: UserDto, OrderModel
|
||||
- External contract representations
|
||||
- No business logic
|
||||
|
||||
8. **Utilities/Helpers** (Adjective/Noun + Utility/Helper)
|
||||
- Cross-cutting functionality: ValidationHelper, EmailUtility
|
||||
- Reusable operations
|
||||
- No domain concepts
|
||||
|
||||
## Relationship Identification
|
||||
|
||||
### Direct Relationships
|
||||
- **Inheritance**: `class Admin extends User` (Is-A)
|
||||
- **Composition**: `class Order { private List<OrderLine> lines; }` (Part-Of)
|
||||
- **Dependency**: `UserService(UserRepository repo)` (Depends-On)
|
||||
|
||||
### Indirect Relationships
|
||||
- **Shared Interfaces**: Implement same interface (Associates-With)
|
||||
- **Common Patterns**: Similar naming or structure (Similar-To)
|
||||
- **Event Connections**: Producer-consumer patterns (Communicates-With)
|
||||
|
||||
### Semantic Relationships
|
||||
- **Temporal**: CreatedBefore, UpdatedAfter
|
||||
- **Spatial**: Contains, LocatedWithin
|
||||
- **Causal**: Triggers, Enables, Prevents
|
||||
- **Logical**: Implies, Contradicts, Equivalent
|
||||
|
||||
## Extraction Workflow
|
||||
|
||||
### Phase 1: Automated Extraction
|
||||
1. Run static analysis tools to identify:
|
||||
- Class/interface definitions
|
||||
- Inheritance hierarchies
|
||||
- Import dependencies
|
||||
- Method signatures
|
||||
|
||||
### Phase 2: Manual Analysis
|
||||
1. Review automated results for semantic accuracy
|
||||
2. Identify implicit concepts not captured by code
|
||||
3. Map business terminology to technical concepts
|
||||
4. Validate relationships with domain experts
|
||||
|
||||
### Phase 3: Ontology Construction
|
||||
1. Organize concepts into hierarchies
|
||||
2. Define relationships between concepts
|
||||
3. Add semantic metadata and descriptions
|
||||
4. Validate completeness and consistency
|
||||
|
||||
### Phase 4: Documentation Generation
|
||||
1. Create visual representations
|
||||
2. Generate textual documentation
|
||||
3. Create interactive navigation
|
||||
4. Establish maintenance processes
|
||||
|
||||
## Quality Assurance
|
||||
|
||||
### Validation Checks
|
||||
- [ ] All identified concepts have clear definitions
|
||||
- [ ] Relationships are correctly classified
|
||||
- [ ] No circular inheritance exists
|
||||
- [ ] Domain terminology is consistent
|
||||
- [ ] Technical and business concepts are aligned
|
||||
|
||||
### Review Process
|
||||
1. **Developer Review**: Technical accuracy and completeness
|
||||
2. **Domain Expert Review**: Business concept validation
|
||||
3. **Architecture Review**: Consistency with system design
|
||||
4. **Documentation Review**: Clarity and usability
|
||||
|
||||
## Maintenance Strategies
|
||||
|
||||
### Continuous Updates
|
||||
- Monitor code changes for new concepts
|
||||
- Update ontology when requirements evolve
|
||||
- Regular reviews with stakeholders
|
||||
- Automated validation checks
|
||||
|
||||
### Version Management
|
||||
- Tag ontology versions with releases
|
||||
- Track concept evolution over time
|
||||
- Maintain change logs
|
||||
- Backward compatibility considerations
|
||||
@@ -0,0 +1,447 @@
|
||||
# Ontological Documentation Templates
|
||||
|
||||
This document provides standardized templates for creating comprehensive ontological documentation for software systems.
|
||||
|
||||
## Core Documentation Templates
|
||||
|
||||
### 1. Concept Definition Template
|
||||
|
||||
```markdown
|
||||
# [Concept Name]
|
||||
|
||||
## Quick Reference
|
||||
- **Type**: [Entity/Value Object/Service/Repository/etc.]
|
||||
- **Category**: [Domain/Business/Infrastructure/etc.]
|
||||
- **Status**: [Active/Deprecated/Experimental]
|
||||
- **Owner**: [Team/Person responsible]
|
||||
|
||||
## Definition
|
||||
[Clear, concise definition of the concept. What is it? What purpose does it serve?]
|
||||
|
||||
## Purpose and Scope
|
||||
**Why this concept exists:**
|
||||
- [Problem it solves]
|
||||
- [Business requirement it addresses]
|
||||
- [Technical necessity]
|
||||
|
||||
**Scope and Boundaries:**
|
||||
- [What's included]
|
||||
- [What's excluded]
|
||||
- [Related but separate concepts]
|
||||
|
||||
## Characteristics
|
||||
### Essential Properties
|
||||
- **Property 1**: [Description] - [Type] - [Constraints]
|
||||
- **Property 2**: [Description] - [Type] - [Constraints]
|
||||
|
||||
### Behavioral Aspects
|
||||
- **Action 1**: [Description] - [Preconditions] - [Postconditions]
|
||||
- **Action 2**: [Description] - [Preconditions] - [Postconditions]
|
||||
|
||||
### Constraints and Rules
|
||||
- [Business rule 1]
|
||||
- [Validation rule 2]
|
||||
- [Integrity constraint 3]
|
||||
|
||||
## Relationships
|
||||
|
||||
### Hierarchical Relationships
|
||||
- **Is-A**: [Parent Concept] - [Rationale]
|
||||
- **Has-A**: [Child Components] - [Composition details]
|
||||
|
||||
### Dependency Relationships
|
||||
- **Depends-On**: [Required Concept] - [Dependency type]
|
||||
- **Required-By**: [Dependent Concept] - [Usage context]
|
||||
|
||||
### Association Relationships
|
||||
- **Associates-With**: [Related Concept] - [Nature of association]
|
||||
- **Similar-To**: [Analogous Concept] - [Comparison points]
|
||||
|
||||
## Implementation
|
||||
|
||||
### Code Representation
|
||||
```python
|
||||
# Example implementation
|
||||
class [ConceptName]:
|
||||
def __init__(self):
|
||||
self.property1 = None
|
||||
self.property2 = None
|
||||
```
|
||||
|
||||
### Data Structure
|
||||
- **Storage Format**: [Database table, JSON, etc.]
|
||||
- **Serialization**: [How it's represented in API/transport]
|
||||
- **Persistence**: [Where and how it's stored]
|
||||
|
||||
### Lifecycle
|
||||
- **Creation**: [How instances are created]
|
||||
- **Evolution**: [How instances change over time]
|
||||
- **Deletion**: [How instances are removed]
|
||||
|
||||
## Examples
|
||||
|
||||
### Concrete Examples
|
||||
1. **Example 1**: [Specific instance with explanation]
|
||||
- [Context]
|
||||
- [Properties]
|
||||
- [Behavior]
|
||||
|
||||
2. **Example 2**: [Another specific instance]
|
||||
- [Context]
|
||||
- [Properties]
|
||||
- [Behavior]
|
||||
|
||||
### Usage Patterns
|
||||
- **Pattern 1**: [Common usage scenario]
|
||||
- **Pattern 2**: [Another usage scenario]
|
||||
|
||||
## Evolution and History
|
||||
- **Created**: [Date] - [Initial reason]
|
||||
- **Major Changes**: [Change history]
|
||||
- **Future Roadmap**: [Planned modifications]
|
||||
|
||||
## Related Documentation
|
||||
- [Link to related concepts]
|
||||
- [Link to implementation details]
|
||||
- [Link to API documentation]
|
||||
- [Link to user documentation]
|
||||
```
|
||||
|
||||
### 2. Relationship Documentation Template
|
||||
|
||||
```markdown
|
||||
# [Relationship Type]: [Source Concept] → [Target Concept]
|
||||
|
||||
## Relationship Overview
|
||||
- **Type**: [Is-A/Part-Of/Depends-On/Associates-With/etc.]
|
||||
- **Source**: [Source Concept Name]
|
||||
- **Target**: [Target Concept Name]
|
||||
- **Strength**: [Strong/Medium/Weak]
|
||||
- **Direction**: [Unidirectional/Bidirectional]
|
||||
|
||||
## Definition
|
||||
[Clear explanation of what this relationship means in the domain context]
|
||||
|
||||
## Rationale
|
||||
**Why this relationship exists:**
|
||||
- [Business reason]
|
||||
- [Technical necessity]
|
||||
- [Domain modeling decision]
|
||||
|
||||
## Characteristics
|
||||
|
||||
### Cardinality
|
||||
- **Source → Target**: [One-to-One/One-to-Many/Many-to-Many]
|
||||
- **Minimum**: [Required/Optional - specify minimum]
|
||||
- **Maximum**: [Unbounded/Specific limit]
|
||||
|
||||
### Constraints
|
||||
- **Existence Constraint**: [Rules about when relationship can exist]
|
||||
- **Deletion Constraint**: [What happens when one end is deleted]
|
||||
- **Update Constraint**: [How relationship changes are handled]
|
||||
|
||||
### Semantic Properties
|
||||
- **Transitivity**: [Whether relationship is transitive]
|
||||
- **Symmetry**: [Whether relationship is symmetric]
|
||||
- **Reflexivity**: [Whether relationship is reflexive]
|
||||
|
||||
## Implementation
|
||||
|
||||
### Code Representation
|
||||
```python
|
||||
# Example implementation
|
||||
class SourceConcept:
|
||||
def __init__(self):
|
||||
self.target_concepts = [] # Relationship implementation
|
||||
```
|
||||
|
||||
### Data Modeling
|
||||
- **Foreign Keys**: [How relationship is stored in database]
|
||||
- **Join Tables**: [If applicable, for many-to-many relationships]
|
||||
- **Indexing**: [Performance considerations]
|
||||
|
||||
### API Representation
|
||||
- **REST Endpoints**: [How relationship is exposed in API]
|
||||
- **GraphQL Schema**: [How relationship appears in GraphQL]
|
||||
- **Serialization**: [How relationship is represented in JSON/XML]
|
||||
|
||||
## Examples
|
||||
|
||||
### Example Instances
|
||||
1. **Example 1**: [Specific relationship instance]
|
||||
- **Source Instance**: [Details]
|
||||
- **Target Instance**: [Details]
|
||||
- **Context**: [When and why this exists]
|
||||
|
||||
2. **Example 2**: [Another specific instance]
|
||||
- **Source Instance**: [Details]
|
||||
- **Target Instance**: [Details]
|
||||
- **Context**: [When and why this exists]
|
||||
|
||||
### Usage Patterns
|
||||
- **Creation Pattern**: [How relationships are established]
|
||||
- **Query Pattern**: [How relationships are accessed]
|
||||
- **Modification Pattern**: [How relationships are changed]
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Business Rules
|
||||
- [Rule 1]: [Description and validation logic]
|
||||
- [Rule 2]: [Description and validation logic]
|
||||
|
||||
### Technical Constraints
|
||||
- [Constraint 1]: [Technical limitation or requirement]
|
||||
- [Constraint 2]: [Performance or scalability consideration]
|
||||
|
||||
## Related Documentation
|
||||
- [Source Concept Documentation]
|
||||
- [Target Concept Documentation]
|
||||
- [Related Relationships]
|
||||
- [Implementation Details]
|
||||
```
|
||||
|
||||
### 3. Domain Model Overview Template
|
||||
|
||||
```markdown
|
||||
# [Domain Name] Domain Model
|
||||
|
||||
## Executive Summary
|
||||
[Brief overview of the domain and its core concepts]
|
||||
|
||||
## Core Concepts Map
|
||||
[Visual representation or hierarchical list of main concepts]
|
||||
|
||||
### Primary Entities
|
||||
- **[Entity 1]**: [Brief description]
|
||||
- **[Entity 2]**: [Brief description]
|
||||
- **[Entity 3]**: [Brief description]
|
||||
|
||||
### Supporting Concepts
|
||||
- **[Value Object 1]**: [Brief description]
|
||||
- **[Service 1]**: [Brief description]
|
||||
- **[Repository 1]**: [Brief description]
|
||||
|
||||
## Concept Hierarchy
|
||||
|
||||
```
|
||||
[Top-level concepts]
|
||||
├── [Category 1]
|
||||
│ ├── [Sub-concept 1.1]
|
||||
│ ├── [Sub-concept 1.2]
|
||||
│ └── [Sub-concept 1.3]
|
||||
├── [Category 2]
|
||||
│ ├── [Sub-concept 2.1]
|
||||
│ └── [Sub-concept 2.2]
|
||||
└── [Category 3]
|
||||
├── [Sub-concept 3.1]
|
||||
└── [Sub-concept 3.2]
|
||||
```
|
||||
|
||||
## Key Relationships
|
||||
|
||||
### Critical Relationships
|
||||
1. **[Relationship 1]**: [Source] → [Target]
|
||||
- [Importance and impact]
|
||||
- [Business significance]
|
||||
|
||||
2. **[Relationship 2]**: [Source] → [Target]
|
||||
- [Importance and impact]
|
||||
- [Business significance]
|
||||
|
||||
### Relationship Patterns
|
||||
- **Composition Pattern**: [Description]
|
||||
- **Dependency Pattern**: [Description]
|
||||
- **Association Pattern**: [Description]
|
||||
|
||||
## Business Rules and Constraints
|
||||
|
||||
### Domain Rules
|
||||
1. **[Rule 1]**: [Description] - [Impact]
|
||||
2. **[Rule 2]**: [Description] - [Impact]
|
||||
|
||||
### Invariants
|
||||
- **Invariant 1**: [What must always be true]
|
||||
- **Invariant 2**: [What must always be true]
|
||||
|
||||
## Processes and Workflows
|
||||
|
||||
### Core Business Processes
|
||||
1. **[Process 1]**
|
||||
- **Trigger**: [What starts the process]
|
||||
- **Steps**: [Sequence of actions]
|
||||
- **Actors**: [Who/what participates]
|
||||
- **Outcomes**: [Results and side effects]
|
||||
|
||||
2. **[Process 2]**
|
||||
- **Trigger**: [What starts the process]
|
||||
- **Steps**: [Sequence of actions]
|
||||
- **Actors**: [Who/what participates]
|
||||
- **Outcomes**: [Results and side effects]
|
||||
|
||||
### State Machines
|
||||
- **[Entity 1] States**: [State transitions and conditions]
|
||||
- **[Entity 2] States**: [State transitions and conditions]
|
||||
|
||||
## Integration Points
|
||||
|
||||
### External Systems
|
||||
- **[System 1]**: [Integration type and purpose]
|
||||
- **[System 2]**: [Integration type and purpose]
|
||||
|
||||
### Data Flows
|
||||
- **Inbound Data**: [What data comes from where]
|
||||
- **Outbound Data**: [What data goes to where]
|
||||
|
||||
## Evolution Strategy
|
||||
|
||||
### Current State
|
||||
- [Description of current domain model state]
|
||||
|
||||
### Planned Changes
|
||||
- **[Change 1]**: [Description and timeline]
|
||||
- **[Change 2]**: [Description and timeline]
|
||||
|
||||
### Migration Strategy
|
||||
- [How to transition from current to future state]
|
||||
|
||||
## Quality Metrics
|
||||
|
||||
### Model Health
|
||||
- **Complexity**: [Assessment of model complexity]
|
||||
- **Consistency**: [How consistent the model is]
|
||||
- **Completeness**: [Gaps and coverage]
|
||||
|
||||
### Usage Metrics
|
||||
- **Most Used Concepts**: [Statistics on concept usage]
|
||||
- **Relationship Density**: [How interconnected concepts are]
|
||||
- **Change Frequency**: [How often concepts change]
|
||||
|
||||
## Related Documentation
|
||||
- [Link to detailed concept documentation]
|
||||
- [Link to API documentation]
|
||||
- [Link to business requirements]
|
||||
- [Link to technical architecture]
|
||||
```
|
||||
|
||||
### 4. Ontology Change Log Template
|
||||
|
||||
```markdown
|
||||
# Ontology Change Log
|
||||
|
||||
## Version [Version Number] - [Date]
|
||||
|
||||
### Summary
|
||||
[Brief overview of changes in this version]
|
||||
|
||||
### Added Concepts
|
||||
- **[Concept Name]**: [Reason for addition] - [Impact]
|
||||
- **[Concept Name]**: [Reason for addition] - [Impact]
|
||||
|
||||
### Modified Concepts
|
||||
- **[Concept Name]**: [Changes made] - [Reason for change] - [Impact]
|
||||
- **[Concept Name]**: [Changes made] - [Reason for change] - [Impact]
|
||||
|
||||
### Removed Concepts
|
||||
- **[Concept Name]**: [Reason for removal] - [Migration strategy]
|
||||
|
||||
### Added Relationships
|
||||
- **[Relationship]**: [Source] → [Target] - [Reason]
|
||||
|
||||
### Modified Relationships
|
||||
- **[Relationship]**: [Source] → [Target] - [Changes] - [Reason]
|
||||
|
||||
### Removed Relationships
|
||||
- **[Relationship]**: [Source] → [Target] - [Reason] - [Impact]
|
||||
|
||||
### Breaking Changes
|
||||
- **[Change Description]**: [Impact on dependent systems] - [Migration required]
|
||||
|
||||
### Migration Guide
|
||||
[Step-by-step guide for adapting to these changes]
|
||||
|
||||
## Previous Versions
|
||||
[Link to previous change logs]
|
||||
```
|
||||
|
||||
## Specialized Templates
|
||||
|
||||
### API Ontology Template
|
||||
```markdown
|
||||
# [API Name] Ontology
|
||||
|
||||
## Resource Model
|
||||
[List of all resources and their relationships]
|
||||
|
||||
## Semantic Operations
|
||||
[CRUD operations and their domain meanings]
|
||||
|
||||
## Media Types
|
||||
[Content types and their semantic significance]
|
||||
|
||||
## Hypermedia Controls
|
||||
[HATEOAS relationships and link semantics]
|
||||
```
|
||||
|
||||
### Database Schema Ontology Template
|
||||
```markdown
|
||||
# [Database Name] Schema Ontology
|
||||
|
||||
## Table Concepts
|
||||
[Tables as domain concepts]
|
||||
|
||||
## Column Semantics
|
||||
[Columns as concept properties]
|
||||
|
||||
## Constraint Logic
|
||||
[Constraints as business rules]
|
||||
|
||||
## Trigger Semantics
|
||||
[Triggers as automated processes]
|
||||
```
|
||||
|
||||
### Event-Driven Architecture Ontology Template
|
||||
```markdown
|
||||
# [System Name] Event Ontology
|
||||
|
||||
## Event Taxonomy
|
||||
[Categorization of all events]
|
||||
|
||||
## Event Relationships
|
||||
[Causal and temporal relationships]
|
||||
|
||||
## Event Semantics
|
||||
[Meaning and significance of events]
|
||||
|
||||
## Process Integration
|
||||
[How events drive business processes]
|
||||
```
|
||||
|
||||
## Template Usage Guidelines
|
||||
|
||||
### When to Use Each Template
|
||||
|
||||
1. **Concept Definition**: Use for every significant domain concept
|
||||
2. **Relationship Documentation**: Use for critical or complex relationships
|
||||
3. **Domain Model Overview**: Use for bounded contexts or major domains
|
||||
4. **Change Log**: Use for every ontology modification
|
||||
5. **Specialized Templates**: Use for specific architectural patterns
|
||||
|
||||
### Quality Checklist
|
||||
|
||||
For each documentation entry:
|
||||
- [ ] Definition is clear and unambiguous
|
||||
- [ ] Purpose and scope are well-defined
|
||||
- [ ] Relationships are accurately described
|
||||
- [ ] Examples are relevant and illustrative
|
||||
- [ ] Implementation details are correct
|
||||
- [ ] Related documentation is linked
|
||||
- [ ] Review date is recorded
|
||||
- [ ] Owner is identified
|
||||
|
||||
### Review Process
|
||||
|
||||
1. **Self-Review**: Check completeness and accuracy
|
||||
2. **Peer Review**: Get feedback from other developers
|
||||
3. **Domain Expert Review**: Validate with domain experts
|
||||
4. **Architecture Review**: Ensure alignment with system architecture
|
||||
5. **Documentation Review**: Check for clarity and usability
|
||||
230
skills/ontological-documentation/reference/ontology_patterns.md
Normal file
230
skills/ontological-documentation/reference/ontology_patterns.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# Ontological Patterns in Software Documentation
|
||||
|
||||
This document describes common ontological patterns and taxonomies found in software systems for creating effective conceptual documentation.
|
||||
|
||||
## Core Ontological Concepts
|
||||
|
||||
### Fundamental Relationship Types
|
||||
|
||||
**Is-A (Inheritance/Hyponymy)**
|
||||
- Description: A concept is a subtype or specialization of another concept
|
||||
- Example: `User` is-a `Person`, `Manager` is-a `Employee`
|
||||
- Code pattern: Class inheritance, interface implementation
|
||||
- Documentation: Use "extends," "inherits from," "is a type of"
|
||||
|
||||
**Part-Of (Mereology/Composition)**
|
||||
- Description: A concept is a component or constituent of another concept
|
||||
- Example: `Wheel` is-part-of `Car`, `Method` is-part-of `Class`
|
||||
- Code pattern: Object composition, nested classes, containment relationships
|
||||
- Documentation: Use "contains," "comprises," "consists of"
|
||||
|
||||
**Instance-Of (Instantiation)**
|
||||
- Description: An object is an instance of a concept/class
|
||||
- Example: `john_doe` is-instance-of `User`, `order_123` is-instance-of `Order`
|
||||
- Code pattern: Object creation, variable assignment
|
||||
- Documentation: Use "instance of," "example of," "specific case of"
|
||||
|
||||
**Depends-On (Dependency)**
|
||||
- Description: A concept requires or relies on another concept
|
||||
- Example: `OrderService` depends-on `PaymentGateway`, `Controller` depends-on `Service`
|
||||
- Code pattern: Import statements, dependency injection, method calls
|
||||
- Documentation: Use "requires," "uses," "relies on"
|
||||
|
||||
**Associates-With (Association)**
|
||||
- Description: A concept has a loose semantic connection to another concept
|
||||
- Example: `User` associates-with `Order`, `Product` associates-with `Category`
|
||||
- Code pattern: Foreign keys, bidirectional references, event subscriptions
|
||||
- Documentation: Use "related to," "connected with," "associated with"
|
||||
|
||||
## Common Software Ontology Patterns
|
||||
|
||||
### Layered Architecture Pattern
|
||||
|
||||
```
|
||||
Presentation Layer
|
||||
├── Controllers
|
||||
├── Views
|
||||
└── ViewModels
|
||||
|
||||
Business Logic Layer
|
||||
├── Services
|
||||
├── Domain Models
|
||||
└── Business Rules
|
||||
|
||||
Data Access Layer
|
||||
├── Repositories
|
||||
├── Data Mappers
|
||||
└── Database Models
|
||||
|
||||
Infrastructure Layer
|
||||
├── External APIs
|
||||
├── Message Queues
|
||||
└── File Storage
|
||||
```
|
||||
|
||||
**Relationships:**
|
||||
- Controllers depend-on Services
|
||||
- Services depend-on Repositories
|
||||
- Repositories depend-on Database Models
|
||||
- ViewModels part-of Presentation Layer
|
||||
|
||||
### Domain-Driven Design Pattern
|
||||
|
||||
**Entities**: Objects with distinct identity
|
||||
- `Customer`, `Order`, `Product`
|
||||
|
||||
**Value Objects**: Objects defined by their attributes
|
||||
- `Address`, `Money`, `DateRange`
|
||||
|
||||
**Aggregates**: Clusters of domain objects
|
||||
- `OrderAggregate` contains `Order`, `OrderLine`, `OrderStatus`
|
||||
|
||||
**Repositories**: Collections of aggregate roots
|
||||
- `CustomerRepository`, `OrderRepository`
|
||||
|
||||
**Domain Services**: Business logic that doesn't fit in entities
|
||||
- `PaymentService`, `ShippingService`
|
||||
|
||||
### MVC Pattern Ontology
|
||||
|
||||
```
|
||||
Model
|
||||
├── Entity Models
|
||||
├── View Models
|
||||
└── Data Transfer Objects
|
||||
|
||||
View
|
||||
├── Templates
|
||||
├── Components
|
||||
└── Layouts
|
||||
|
||||
Controller
|
||||
├── Action Methods
|
||||
├── Route Handlers
|
||||
└── API Endpoints
|
||||
```
|
||||
|
||||
**Relationships:**
|
||||
- Controllers manipulate Models
|
||||
- Controllers select Views
|
||||
- Views display Models
|
||||
- Models notify Views of changes
|
||||
|
||||
### Microservices Pattern Ontology
|
||||
|
||||
**Service Categories:**
|
||||
- **API Gateway**: Entry point for external requests
|
||||
- **Core Services**: Business logic services
|
||||
- **Supporting Services**: Shared functionality (auth, logging)
|
||||
- **Data Services**: Database operations
|
||||
|
||||
**Service Relationships:**
|
||||
- `API Gateway` routes-to `Core Services`
|
||||
- `Core Services` call `Supporting Services`
|
||||
- `Services` publish-to `Message Broker`
|
||||
- `Services` read-from `Configuration Service`
|
||||
|
||||
## Taxonomy Classification Systems
|
||||
|
||||
### Functional Classification
|
||||
|
||||
**By Purpose:**
|
||||
- Business Logic Components
|
||||
- Data Management Components
|
||||
- Presentation Components
|
||||
- Integration Components
|
||||
- Infrastructure Components
|
||||
|
||||
**By Lifecycle:**
|
||||
- Singleton Components
|
||||
- Scoped Components
|
||||
- Transient Components
|
||||
- Request-scoped Components
|
||||
|
||||
### Structural Classification
|
||||
|
||||
**By Abstraction Level:**
|
||||
- Interface Layer (highest abstraction)
|
||||
- Service Layer
|
||||
- Repository Layer
|
||||
- Data Layer (lowest abstraction)
|
||||
|
||||
**By Coupling:**
|
||||
- Tightly Coupled Components
|
||||
- Loosely Coupled Components
|
||||
- Decoupled Components
|
||||
|
||||
## Documentation Templates
|
||||
|
||||
### Concept Documentation Template
|
||||
|
||||
```markdown
|
||||
# [Concept Name]
|
||||
|
||||
## Definition
|
||||
Brief, clear definition of the concept
|
||||
|
||||
## Purpose
|
||||
Why this concept exists and what problem it solves
|
||||
|
||||
## Characteristics
|
||||
Key attributes and properties of the concept
|
||||
|
||||
## Relationships
|
||||
- **Is-A**: [Parent concepts]
|
||||
- **Part-Of**: [Containing concepts]
|
||||
- **Depends-On**: [Required concepts]
|
||||
- **Associates-With**: [Related concepts]
|
||||
|
||||
## Examples
|
||||
Concrete examples of the concept in use
|
||||
|
||||
## Implementation Notes
|
||||
Technical implementation details and considerations
|
||||
```
|
||||
|
||||
### Relationship Documentation Template
|
||||
|
||||
```markdown
|
||||
# [Relationship Type]: [Source] → [Target]
|
||||
|
||||
## Relationship Description
|
||||
Description of the semantic relationship
|
||||
|
||||
## Cardinality
|
||||
- One-to-One, One-to-Many, Many-to-Many
|
||||
- Required vs Optional
|
||||
|
||||
## Constraints
|
||||
Rules and limitations on the relationship
|
||||
|
||||
## Implementation
|
||||
How the relationship is implemented in code
|
||||
|
||||
## Examples
|
||||
Specific examples of the relationship
|
||||
```
|
||||
|
||||
## Ontology Validation Rules
|
||||
|
||||
### Consistency Rules
|
||||
|
||||
1. **No Circular Inheritance**: A class cannot inherit from itself (directly or indirectly)
|
||||
2. **Complete Relationships**: All referenced concepts must be defined
|
||||
3. **Consistent Naming**: Use consistent terminology throughout the ontology
|
||||
4. **Proper Abstraction Levels**: Related concepts should be at similar abstraction levels
|
||||
|
||||
### Completeness Rules
|
||||
|
||||
1. **Defined Concepts**: All concepts must have clear definitions
|
||||
2. **Documented Relationships**: All relationships should be explicitly documented
|
||||
3. **Coverage**: Important domain concepts should be represented
|
||||
4. **Hierarchy**: Concepts should be organized in logical hierarchies
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. **Use Standard Terminology**: Prefer established domain vocabulary
|
||||
2. **Avoid Ambiguity**: Define terms clearly and consistently
|
||||
3. **Maintain Separation**: Separate conceptual models from implementation details
|
||||
4. **Document Rationale**: Explain why certain relationships exist
|
||||
5. **Regular Review**: Update ontology as system evolves
|
||||
Reference in New Issue
Block a user