coulomb/markitect-main
2
0
Fork 0
Code Issues 60 Pull Requests Actions 1 Projects 12 Releases 1 Wiki Activity

feat: Add practical use case examples and comprehensive gap analysis

Browse Source 
- Created invoice template demonstrating business document requirements
- Added design pattern example showing knowledge management use case
- Included sample data file for template + data scenarios
- Comprehensive gap analysis identifying 6 critical tooling limitations
- Documented 3-phase development roadmap for enhanced capabilities
- Based on Issue #63 use case brainstorming requirements

Key gaps identified:
1. Template engine for dynamic document generation
2. Calculation system for mathematical operations
3. Batch processing for multi-document workflows
4. External data integration capabilities
5. Cross-document relationship management
6. Advanced output format support

Ready for requirements engineering and epic decomposition.

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2025-10-02 10:16:16 +02:00
parent cde2805078
commit 27f4f6b1b1
4 changed files with 403 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
USE_CASES_GAP_ANALYSIS.md Normal file
View File

@@ -0,0 +1,180 @@
# MarkiTect Use Cases & Tooling Gap Analysis
**Analysis Date:** 2025-10-02
**Based on:** Issue #63 Use Case Brainstorming
**Examples Created:** Invoice template, Design pattern document
## Current MarkiTect Strengths ✅
### **Document Structure & Metadata**
- **Frontmatter parsing**: Full support for YAML/JSON/TOML metadata
- **Contentmatter extraction**: MultiMarkdown key-value pairs from content body
- **Tailmatter management**: QA checklists, editorial workflow, agent configurations
- **Schema generation**: Automatic JSON schema creation from document structure
- **Validation**: Schema-based document validation with detailed error reporting
### **Analysis & Querying**
- **AST parsing**: Complete document structure analysis
- **Database storage**: SQLite integration with comprehensive querying
- **Statistics**: Detailed document metrics and analytics
- **CLI interface**: Comprehensive command set for all operations
### **Tested Successfully**
- ✅ Complex document metadata extraction (invoice frontmatter)
- ✅ Nested tailmatter access (pattern complexity scores)
- ✅ Quality assurance workflows (QA checklists with progress tracking)
- ✅ Schema generation for structured documents
## Identified Gaps & Missing Capabilities ❌
### **1. Template Engine & Dynamic Generation**
**Problem:** No way to generate documents from templates + data
**Use Cases Affected:** Invoices, letters, offers, contracts, reports
**Current Limitation:** Templates contain placeholder syntax but no rendering engine
```markdown
# Current: Static template with {{placeholders}}
**Customer:** {{customer.name}}
**Total:** {{total}} {{currency}}
# Needed: Rendered output
**Customer:** Acme Corporation
**Total:** 9514.05 EUR
```
**Recommended Solution:** Template rendering system with variable substitution
### **2. Calculation & Business Logic Engine**
**Problem:** No mathematical operations or formula evaluation
**Use Cases Affected:** Invoices, financial reports, pricing calculations
**Current Limitation:** Cannot compute totals, taxes, or derived values
```yaml
# Current: Manual calculations in data file
subtotal: 7995.00
tax_amount: 1519.05 # Manually calculated
total: 9514.05 # Manually calculated
# Needed: Automatic calculation
calculations:
subtotal: "{{sum line_items 'total'}}"
tax_amount: "{{multiply subtotal tax_rate}}"
total: "{{add subtotal tax_amount}}"
```
**Recommended Solution:** Expression evaluation engine with mathematical functions
### **3. Multi-Document Relationships**
**Problem:** No cross-document references or relationship management
**Use Cases Affected:** Documentation sets, linked specifications, project portfolios
**Current Limitation:** Each document is isolated
```markdown
# Needed: Document linking and validation
Related Documents:
- Specification: [ref:SPEC-001] # Validate reference exists
- Parent Project: [ref:PROJ-2025-Q4] # Auto-update if renamed
```
**Recommended Solution:** Document relationship system with reference validation
### **4. Batch Processing & Workflows**
**Problem:** No multi-document operations or automation
**Use Cases Affected:** Mass generation, batch validation, workflow automation
**Current Limitation:** All operations are single-document focused
```bash
# Needed: Batch operations
markitect generate-batch --template invoice.md --data customers.csv --output ./invoices/
markitect validate-all --schema contract.schema.json ./contracts/*.md
markitect workflow run --pipeline monthly-reports.yaml
```
**Recommended Solution:** Batch processing commands and workflow orchestration
### **5. External Data Integration**
**Problem:** No integration with external data sources
**Use Cases Affected:** CRM integration, API data, database synchronization
**Current Limitation:** All data must be manually prepared
```bash
# Needed: Data source integration
markitect import --source database --query "SELECT * FROM customers" --template customer.md
markitect sync --api https://api.example.com/contacts --format contact.md
markitect export --target csv --fields "name,email,status" ./contacts/*.md
```
**Recommended Solution:** Data connector system for external sources
### **6. Advanced Output Formats**
**Problem:** Limited output format support
**Use Cases Affected:** Professional documents, presentations, reports
**Current Limitation:** Primarily markdown and JSON output
```bash
# Needed: Professional output formats
markitect export --format pdf --template letterhead.pdf invoice.md
markitect convert --to docx --styles corporate.docx proposal.md
markitect generate --format html --css professional.css report.md
```
**Recommended Solution:** Multi-format export system with styling support
## Priority Use Case Analysis
### **High Impact, High Feasibility**
1. **Template Engine** - Core functionality for many business use cases
2. **Calculation Engine** - Essential for financial and quantitative documents
3. **Batch Processing** - Automation foundation for scaling operations
### **Medium Impact, Medium Feasibility**
4. **Multi-Document Relationships** - Important for complex documentation
5. **External Data Integration** - Valuable for business system integration
### **High Impact, Lower Feasibility**
6. **Advanced Output Formats** - Important but complex implementation
## Recommended Next Steps
### **Phase 1: Core Template System** (Issue #64 proposal)
- Implement basic template rendering with variable substitution
- Add mathematical expression evaluation
- Support for conditional content and loops
### **Phase 2: Batch Operations** (Issue #65 proposal)
- Multi-document processing commands
- Data-driven document generation from CSV/JSON
- Batch validation and reporting
### **Phase 3: Integration & Export** (Issue #66 proposal)
- External data source connectors
- Advanced output format support
- Cross-document relationship management
## Example Use Cases Ready for Implementation
### **1. Invoice Generation System**
```bash
# With proposed template engine
markitect generate --template invoice.md --data customer-orders.csv --output ./invoices/
markitect validate-batch --schema invoice.schema.json ./invoices/*.md
markitect export --format pdf --output ./invoices/pdf/ ./invoices/*.md
```
### **2. Pattern Library Management**
```bash
# With proposed relationship system
markitect link-patterns --category "Data Access" --validate-references
markitect generate-index --template pattern-index.md --source ./patterns/
markitect validate-consistency --check-crossrefs ./patterns/*.md
```
### **3. Compliance Documentation**
```bash
# With proposed workflow system
markitect workflow run --pipeline iso27001-audit.yaml
markitect generate-report --template compliance-report.md --data audit-results.json
markitect validate-requirements --standard iso27001 ./documentation/
```
These practical applications reveal significant opportunities to enhance MarkiTect's value proposition for real-world business use cases.

124
examples/design_pattern.md Normal file
View File

@@ -0,0 +1,124 @@
---
pattern_name: "Repository Pattern"
category: "Data Access"
difficulty: "intermediate"
languages: ["Java", "C#", "Python", "TypeScript"]
related_patterns: ["Unit of Work", "Data Mapper", "Active Record"]
version: "1.0"
author: "Design Patterns Team"
date_created: "2025-10-02"
status: "published"
---
# Repository Pattern
Pattern Type: Behavioral
Category: Data Access Patterns
Difficulty Level: Intermediate
## Intent
Encapsulate the logic needed to access data sources. The Repository pattern centralizes common data access functionality, providing better maintainability and decoupling infrastructure or technology used to access databases from the domain model layer.
## Problem
Direct database access from business logic creates:
- **Tight Coupling**: Business logic depends on specific data access technology
- **Code Duplication**: Similar queries repeated across the application
- **Testing Difficulties**: Hard to unit test without actual database
- **Technology Lock-in**: Difficult to change data access technology
Problem Context: Large applications with complex data access requirements
Impact: High maintenance cost, reduced testability, technology dependencies
## Solution
Create a uniform interface for accessing domain objects that:
1. **Abstracts Data Access**: Hide implementation details behind interface
2. **Centralizes Queries**: Common data access logic in one place
3. **Enables Testing**: Interface allows for easy mocking
4. **Supports Multiple Sources**: Can work with different data stores
Solution Approach: Interface-based abstraction layer
Key Benefit: Separation of concerns between domain and data access
## Structure
```
Repository Interface → Concrete Repository → Data Source
↑ ↓
Domain Layer Infrastructure Layer
```
## Implementation
Implementation Language: Python
Framework: SQLAlchemy
Database: PostgreSQL
```python
# Repository Interface
class UserRepository(ABC):
@abstractmethod
def find_by_id(self, user_id: int) -> Optional[User]:
pass
@abstractmethod
def find_by_email(self, email: str) -> Optional[User]:
pass
@abstractmethod
def save(self, user: User) -> User:
pass
```
## Consequences
**Benefits:**
- ✅ Improved testability through dependency injection
- ✅ Separation of concerns between domain and data access
- ✅ Centralized data access logic reduces duplication
- ✅ Technology independence in domain layer
**Drawbacks:**
- ❌ Additional abstraction layer increases complexity
- ❌ May lead to over-engineering for simple applications
- ❌ Performance overhead from abstraction
- ❌ Learning curve for developers
Trade-offs: Flexibility vs. Complexity
When to avoid: Simple CRUD applications, prototype projects
## Known Uses
- **Enterprise Applications**: Banking systems, e-commerce platforms
- **Domain-Driven Design**: Clean architecture implementations
- **Testing Scenarios**: Applications requiring extensive unit testing
- **Multi-tenant Systems**: Applications with multiple data sources
Real-world Examples: Spring Data repositories, Entity Framework repositories
---
```yaml tailmatter
qa_checklist:
- requirement: "Code examples tested and verified"
complete: true
- requirement: "Related patterns cross-referenced"
complete: false
- requirement: "Real-world examples validated"
complete: true
editorial:
status: "review_complete"
reviewer: "architecture.team@example.com"
version: "1.0"
approval_required: false
last_updated: "2025-10-02"
pattern_metadata:
complexity_score: 6.5
usage_frequency: "high"
maturity_level: "stable"
community_rating: 4.2
```

37
examples/invoice_data.json Normal file
View File

@@ -0,0 +1,37 @@
{
"invoice_number": "INV-2025-001",
"date": "2025-10-02",
"due_date": "2025-11-01",
"currency": "EUR",
"tax_rate": 0.19,
"tax_rate_percent": "19",
"customer": {
"company": "Acme Corporation",
"contact": "John Smith",
"address": "123 Business Ave, 54321 Commerce City",
"email": "john.smith@acme.example"
},
"line_items": [
{
"description": "MarkiTect Pro License (1 year)",
"quantity": 5,
"unit_price": 299.00,
"total": 1495.00
},
{
"description": "Implementation & Training",
"quantity": 40,
"unit_price": 150.00,
"total": 6000.00
},
{
"description": "Priority Support Package",
"quantity": 1,
"unit_price": 500.00,
"total": 500.00
}
],
"subtotal": 7995.00,
"tax_amount": 1519.05,
"total": 9514.05
}

62
examples/invoice_template.md Normal file
View File

@@ -0,0 +1,62 @@
---
document_type: "invoice"
invoice_number: "INV-2025-001"
date: "2025-10-02"
due_date: "2025-11-01"
currency: "EUR"
tax_rate: 0.19
status: "draft"
---
# Invoice {{invoice_number}}
**Date:** {{date}}
**Due Date:** {{due_date}}
## Bill To
Company: {{customer.company}}
Contact: {{customer.contact}}
Address: {{customer.address}}
Email: {{customer.email}}
## Bill From
Company: MarkiTect Solutions GmbH
Address: Innovation Street 42, 12345 Tech City
Email: billing@markitect.example
Tax ID: DE123456789
## Line Items
| Description | Quantity | Unit Price | Total |
|-------------|----------|------------|--------|
{{#each line_items}}
| {{description}} | {{quantity}} | {{unit_price}} {{../currency}} | {{multiply quantity unit_price}} {{../currency}} |
{{/each}}
## Summary
**Subtotal:** {{subtotal}} {{currency}}
**Tax ({{tax_rate_percent}}%):** {{tax_amount}} {{currency}}
**Total:** {{total}} {{currency}}
---
```yaml tailmatter
qa_checklist:
- requirement: "All line items verified"
complete: false
- requirement: "Customer details confirmed"
complete: false
- requirement: "Tax calculation verified"
complete: false
editorial:
status: "draft"
reviewer: "finance.team@markitect.example"
approval_required: true
calculations:
subtotal: "{{sum line_items 'total'}}"
tax_amount: "{{multiply subtotal tax_rate}}"
total: "{{add subtotal tax_amount}}"
```