Oktuple Technical Documentation

Appearance

Domain Model ​

Overview ​

The Oktuple domain model is built around the concept of hierarchical project management with flexible, extensible structures. The system uses a node-based architecture where projects, tasks, and organizational elements are represented as interconnected nodes (ENodes) with rich metadata and relationships.

Core Entities ​

ENode (Project Node) ​

Purpose: The fundamental building block representing any organizational unit in the system

Key Attributes:

  • id: Unique identifier
  • title: Human-readable name
  • description: Detailed description
  • type: Classification (project, sprint, epic, story, etc.)
  • parent_id: Hierarchical relationship
  • template_id: Associated template
  • domain: Business domain classification
  • prefix: Short identifier
  • meta: Flexible JSON metadata
  • archived: Soft deletion flag
  • has_sprint: Sprint management capability
  • has_limited: Access control flag

Relationships:

  • Hierarchical: Parent-child relationships for nested structures
  • Template: Links to workflow templates
  • People: Team member assignments
  • Addons: Extended functionality
  • Markers: Visual indicators and tags

Use Cases:

  • Project organization
  • Sprint planning
  • Epic breakdown
  • Team structure
  • Workflow templates

Issue (Work Item) ​

Purpose: Represents individual work items, tasks, bugs, or feature requests

Key Attributes:

  • id: Unique identifier
  • title: Task description
  • type: Work item classification
  • effort: Estimated work effort
  • status: Current state
  • priority: Importance level
  • tags: Categorization labels
  • meta: Flexible metadata
  • cfs: Custom fields
  • stats: Performance metrics
  • due_at: Deadline
  • start_at: Start date
  • completed_at: Completion date

Relationships:

  • ENode: Belongs to project structure
  • Parent/Child: Hierarchical task breakdown
  • Dependencies: Links to other issues
  • Attachments: File uploads
  • Comments: Discussion threads
  • Reminders: Time-based notifications
  • Template: Workflow template

Use Cases:

  • Task management
  • Bug tracking
  • Feature development
  • Sprint planning
  • Time tracking

People (Team Members) ​

Purpose: Represents users and their roles within the system

Key Attributes:

  • id: Unique identifier
  • name: Display name
  • type: User classification
  • pl: Permission level
  • mpath: Materialized path for hierarchy
  • config: User preferences
  • enode_id: Associated project

Relationships:

  • ENode: Project assignment
  • Roles: Permission assignments
  • User Accounts: Authentication details

Use Cases:

  • Team management
  • Access control
  • Role assignment
  • Permission management

Template ​

Purpose: Defines reusable project structures and workflows

Key Attributes:

  • id: Unique identifier
  • title: Template name
  • framework: Methodology (Agile, Kanban, etc.)
  • rules: Workflow configuration
  • enode_id: Associated project
  • is_default: Default template flag
  • template_type: Classification

Relationships:

  • ENodes: Project structures
  • Issues: Task templates
  • Owner: Template creator

Use Cases:

  • Project setup
  • Workflow standardization
  • Methodology implementation
  • Process improvement

Addon ​

Purpose: Extends core functionality with custom features and metadata

Key Attributes:

  • id: Unique identifier
  • type: Addon classification
  • title: Display name
  • metadata: Flexible data storage
  • mpath: Hierarchical path
  • active: Enabled status
  • is_abstract: Abstract addon flag

Relationships:

  • ENode: Associated project
  • Parent: Hierarchical structure

Use Cases:

  • Custom fields
  • Workflow extensions
  • Integration points
  • Feature plugins

Attachment ​

Purpose: Manages file uploads and document storage

Key Attributes:

  • id: Unique identifier
  • issue_id: Associated work item
  • key: File identifier
  • value: File metadata
  • owner_id: Uploader

Relationships:

  • Issue: Work item association

Use Cases:

  • Document management
  • File sharing
  • Requirement documents
  • Design assets

Purpose: Manages relationships and dependencies between work items

Key Attributes:

  • id: Unique identifier
  • type: Relationship type
  • from: Source issue
  • to: Target issue
  • resolve: Resolution status
  • owner_id: Creator

Use Cases:

  • Dependency management
  • Blocking relationships
  • Related work items
  • Impact analysis

Role ​

Purpose: Defines permission sets and access levels

Key Attributes:

  • id: Unique identifier
  • name: Role name
  • enode_id: Project scope
  • hierarchy_path: Permission inheritance
  • is_default: Default role flag

Relationships:

  • Permissions: Granular access rights
  • Users: Role assignments
  • Hierarchy: Role inheritance

Use Cases:

  • Access control
  • Permission management
  • Role-based security
  • Team organization

Data Relationships ​

Hierarchical Structure ​

ENode (Project)
├── ENode (Sprint)
│   ├── ENode (Epic)
│   │   ├── Issue (Story)
│   │   ├── Issue (Task)
│   │   └── Issue (Bug)
│   └── ENode (Epic)
│       ├── Issue (Story)
│       └── Issue (Task)
└── ENode (Sprint)
    └── Issue (Story)

Entity Relationships ​

ENode ←→ People (Team Assignment)
  ↓
Issue (Work Items)
  ↓
├── Attachment (Files)
├── Comment (Discussion)
├── Reminder (Notifications)
└── Links (Dependencies)

Template System ​

Template (Workflow)
  ↓
ENode (Project Structure)
  ↓
Issue (Task Templates)
  ↓
Addon (Custom Fields)

Data Flow Patterns ​

1. Project Creation Flow ​

Template Selection → ENode Creation → People Assignment → Issue Setup

2. Work Item Lifecycle ​

Issue Creation → Assignment → Work → Review → Completion

3. Data Synchronization ​

Database Change → Logical Replication → Search Indexing → Real-time Updates

Metadata and Extensibility ​

Flexible Metadata ​

The system uses JSON fields (meta, cfs, config) to store:

  • Custom fields
  • Workflow state
  • User preferences
  • Integration data
  • Business rules

Addon System ​

Addons provide:

  • Custom functionality
  • Extended data models
  • Integration capabilities
  • Workflow extensions
  • Reporting features

Data Consistency ​

ACID Compliance ​

  • Atomicity: All operations succeed or fail together
  • Consistency: Data integrity maintained
  • Isolation: Concurrent operations don't interfere
  • Durability: Changes persist permanently

Synchronization ​

  • Real-time: Immediate updates via WebSocket
  • Search Engines: Elasticsearch and Typesense sync
  • Fallback: Redis queue for reliability
  • Audit Trail: Complete change history

Performance Considerations ​

Indexing Strategy ​

  • Primary Keys: Unique identifiers
  • Foreign Keys: Relationship lookups
  • Composite Indexes: Multi-field queries
  • Full-text Search: Content indexing

Caching Strategy ​

  • Redis: Frequently accessed data
  • Application: In-memory caching
  • Database: Query result caching
  • Search: Index caching

Security Model ​

Access Control ​

  • Authentication: Casdoor integration
  • Authorization: Role-based permissions
  • Data Isolation: Project-level access
  • Audit Logging: Complete activity trail

Data Protection ​

  • Input Validation: Zod schema validation
  • SQL Injection: Prisma ORM protection
  • XSS Prevention: Output sanitization
  • CSRF Protection: Token validation

Future Considerations ​

Planned Enhancements ​

  • GraphQL: Alternative query interface
  • Event Sourcing: Enhanced audit capabilities
  • Machine Learning: Predictive analytics

Scalability Improvements ​

  • Sharding: Database partitioning
  • Caching: Distributed caching
  • Queue Management: Advanced job processing