Decision Management¶

Referenced Files in This Document - apps/service/core/decision.py - apps/shared/models/decision.py - apps/shared/schemas/decision.py - apps/service/routes/decisions.py - apps/shared/models/history.py - apps/service/routes/history.py - apps/service/core/pipeline.py - apps/service/core/types.py - apps/shared/models/action_log.py - apps/service/api/ai.py

Introduction¶

Nexo's decision management system provides a comprehensive framework for managing content classification decisions through an automated-to-manual workflow pipeline. The system handles everything from initial AI-powered classification to human review processes, ensuring quality control while maintaining scalability for large media libraries.

The decision management system serves as the central coordination point between automated processing pipelines and manual review workflows, providing audit trails, notification systems, and compliance tracking for all decision-related activities.

Project Structure¶

The decision management system is organized across multiple layers following a clean architecture pattern:

graph TB
subgraph "API Layer"
Routes[Routes/Controllers]
Schemas[Schemas/DTOs]
end
subgraph "Service Layer"
Core[Core Business Logic]
UseCases[Use Cases]
Pipeline[Processing Pipeline]
end
subgraph "Data Layer"
Models[Database Models]
History[History Tracking]
ActionLog[Action Logs]
end
subgraph "External Services"
AI[AI Classification]
Notify[Notification System]
end
Routes --> Core
Schemas --> Routes
Core --> UseCases
UseCases --> Pipeline
Core --> Models
Core --> History
Core --> ActionLog
Pipeline --> AI
Core --> Notify

Diagram sources - apps/service/routes/decisions.py - apps/service/core/decision.py - apps/shared/models/decision.py

Core Components¶

Decision Model Architecture¶

The decision management system centers around several key components that work together to manage the complete lifecycle of content decisions:

Decision Entity¶

The core decision entity represents individual content classification decisions with metadata about the decision-making process, confidence scores, and audit information.

Decision Types¶

The system supports multiple decision types including automatic classification results, manual reviews, and hybrid approaches combining both automated and human input.

State Management¶

Each decision progresses through defined states from creation to final approval or rejection, with transitions governed by business rules and user permissions.

Section sources - apps/shared/models/decision.py - apps/service/core/types.py

Data Flow Architecture¶

The decision management system implements a layered data flow architecture:

sequenceDiagram
participant Client as "Client Application"
participant API as "Decision API"
participant Service as "Decision Service"
participant Pipeline as "Processing Pipeline"
participant DB as "Database"
participant Notify as "Notification System"
Client->>API : Create Decision Request
API->>Service : Validate & Process Request
Service->>Pipeline : Execute Classification
Pipeline-->>Service : Classification Results
Service->>DB : Store Decision & Metadata
Service->>Notify : Send Notifications
Service-->>API : Decision Created
API-->>Client : Response with Decision ID
Note over Client,DB : Complete decision lifecycle tracking

Diagram sources - apps/service/routes/decisions.py - apps/service/core/decision.py - apps/service/core/pipeline.py

Architecture Overview¶

The decision management system follows a microservices-inspired architecture within the monolithic application structure, providing clear separation of concerns and extensibility points.

System Components¶

classDiagram
class DecisionManager {
+create_decision(request) Decision
+update_decision(id, updates) Decision
+approve_decision(id, reviewer) Decision
+reject_decision(id, reviewer, reason) Decision
+get_decision_history(id) History[]
+bulk_update_decisions(updates) BulkResult
}
class DecisionWorkflow {
+execute_workflow(decision) WorkflowResult
+validate_transition(from_state, to_state) bool
+apply_business_rules(decision) RuleResult
+escalate_decision(decision, reason) Escalation
}
class AuditTrail {
+log_action(action, details) void
+get_audit_log(entity_id) AuditEntry[]
+generate_compliance_report() Report
}
class NotificationService {
+send_decision_request(user, decision) void
+send_approval_notification(user, decision) void
+send_rejection_notification(user, decision) void
}
DecisionManager --> DecisionWorkflow : "uses"
DecisionManager --> AuditTrail : "logs actions"
DecisionManager --> NotificationService : "sends notifications"
DecisionWorkflow --> AuditTrail : "records transitions"

Diagram sources - apps/service/core/decision.py - apps/shared/models/action_log.py

Detailed Component Analysis¶

Decision Lifecycle Management¶

The decision lifecycle encompasses the complete journey from initial classification to final resolution, with each stage providing specific functionality and validation.

Creation Phase¶

Decision creation involves capturing initial classification results, setting up audit trails, and determining whether manual review is required based on confidence thresholds and business rules.

Review Phase¶

Manual review processes provide interfaces for human evaluators to examine content, override automated decisions, and provide detailed reasoning for their choices.

Resolution Phase¶

Final decisions are recorded with full audit trails, notifications are sent to relevant stakeholders, and downstream systems are updated accordingly.

Section sources - apps/service/core/decision.py - apps/shared/models/decision.py

Processing Pipeline Integration¶

The decision management system integrates seamlessly with the broader content processing pipeline, receiving automated classification results and triggering appropriate review workflows.

Automated Classification Input¶

The system accepts classification results from various AI models, including image classifiers, document parsers, and content analyzers, with standardized result formats.

Confidence-Based Routing¶

Decisions with high confidence scores may bypass manual review, while low-confidence results are automatically routed to human reviewers based on configurable thresholds.

Hybrid Decision Making¶

The system supports hybrid approaches where automated and manual decisions are combined, with weighted scoring and conflict resolution mechanisms.

Section sources - apps/service/core/pipeline.py - apps/service/api/ai.py

Decision Workflow¶

The decision workflow defines the complete process flow from initial content analysis to final resolution, incorporating both automated and manual stages.

Workflow States¶

stateDiagram-v2
[*] --> Created : "Initial Classification"
Created --> PendingReview : "Low Confidence Score"
Created --> Approved : "High Confidence Auto-Approve"
Created --> Rejected : "High Confidence Auto-Reject"
PendingReview --> UnderReview : "Reviewer Assigned"
UnderReview --> Approved : "Manual Approval"
UnderReview --> Rejected : "Manual Rejection"
UnderReview --> PendingReview : "Additional Info Needed"
Approved --> Finalized : "Audit Complete"
Rejected --> Finalized : "Audit Complete"
Finalized --> [*]
state "PendingReview" {
[*] --> AwaitingAssignment
AwaitingAssignment --> UnderReview : "Assigned"
AwaitingAssignment --> Escalated : "Escalation Required"
}
state "UnderReview" {
[*] --> InProgress
InProgress --> Completed : "Decision Made"
InProgress --> Escalated : "Escalation Triggered"
}

Diagram sources - apps/service/core/decision.py - apps/shared/models/decision.py

Workflow Triggers and Conditions¶

The workflow incorporates multiple trigger points and conditional logic:

Automatic Triggers¶

Confidence score thresholds
Content type-specific rules
Time-based escalation policies
Quality assurance sampling

Manual Triggers¶

User-initiated reviews
Manager overrides
Compliance requirements
Customer complaints

Section sources - apps/service/core/decision.py

Business Rules and State Transitions¶

The decision management system enforces strict business rules governing state transitions and decision validity.

State Transition Matrix¶

Current State	Allowed Transitions	Conditions	Actors
Created	PendingReview, Approved, Rejected	Confidence < threshold	System
PendingReview	UnderReview, Escalated	Reviewer available	System
UnderReview	Approved, Rejected, PendingReview	Review completed	Human Reviewer
Approved	Finalized	Audit complete	System
Rejected	Finalized	Audit complete	System

Validation Rules¶

Confidence Thresholds¶

High confidence (>90%): Auto-approve/reject
Medium confidence (70-90%): Conditional review
Low confidence (<70%): Mandatory review

Content Type Rules¶

Different content categories have specific review requirements
Sensitive content always requires manual review
Educational content may have relaxed standards

Temporal Constraints¶

Review deadlines based on content urgency
Escalation timers for unreviewed items
Audit retention periods

Section sources - apps/service/core/decision.py - apps/shared/models/decision.py

Bulk Operations and Scalability¶

The decision management system provides robust support for bulk operations to handle large-scale content processing efficiently.

Bulk Decision Creation¶

flowchart TD
Start([Bulk Operation Start]) --> LoadBatch["Load Batch of Items"]
LoadBatch --> ClassifyItems["Run Automated Classification"]
ClassifyItems --> AnalyzeResults["Analyze Confidence Scores"]
AnalyzeResults --> RouteDecisions{"Route Based on Confidence"}
RouteDecisions --> |High Confidence| AutoProcess["Auto-Process Decisions"]
RouteDecisions --> |Low Confidence| QueueReview["Queue for Review"]
AutoProcess --> UpdateStatus["Update Status & Audit Trail"]
QueueReview --> AssignReviewers["Assign Reviewers"]
AssignReviewers --> UpdateStatus
UpdateStatus --> GenerateReport["Generate Processing Report"]
GenerateReport --> End([Operation Complete])

Diagram sources - apps/service/core/decision.py - apps/service/routes/decisions.py

Performance Optimization Strategies¶

Batch Processing¶

Chunk-based processing to prevent memory overflow
Parallel processing for independent decisions
Database connection pooling for concurrent operations

Caching Strategies¶

Decision template caching for similar content types
Reviewer workload distribution caching
Confidence score caching for reprocessing scenarios

Monitoring and Metrics¶

Processing throughput monitoring
Error rate tracking per batch
Resource utilization metrics

Section sources - apps/service/routes/decisions.py

Notification System Integration¶

The decision management system integrates with a comprehensive notification system to keep stakeholders informed throughout the decision lifecycle.

Notification Types¶

Event Type	Recipients	Channels	Timing
Decision Created	Content Owners, Reviewers	Email, Push, Dashboard	Immediate
Review Assigned	Assigned Reviewers	Email, Push, Dashboard	Immediate
Decision Approved	Content Owners, Managers	Email, Dashboard	Within 1 hour
Decision Rejected	Content Owners, Support	Email, Dashboard, Ticket	Within 1 hour
Escalation Triggered	Senior Reviewers, Managers	Email, Phone, Dashboard	Immediate

Notification Templates¶

The system supports customizable notification templates with dynamic content insertion, localization support, and channel-specific formatting.

Delivery Guarantees¶

Retry mechanisms for failed deliveries
Delivery confirmation tracking
Fallback channels for critical notifications
Quiet hours and priority routing

Section sources - apps/service/core/decision.py

Audit Trail and Compliance¶

The decision management system maintains comprehensive audit trails to ensure regulatory compliance and provide transparency into decision-making processes.

Audit Trail Components¶

Decision History¶

Complete chronological record of all decision-related actions, including who made changes, when they occurred, and what the previous state was.

Evidence Collection¶

Associated evidence files, screenshots, and supporting documentation for each decision.

Compliance Reports¶

Automated report generation for regulatory requirements, including decision statistics, reviewer performance, and policy adherence metrics.

Data Retention Policies¶

Minimum retention periods based on content type and jurisdiction
Secure archival procedures for long-term storage
Privacy-preserving anonymization for historical analysis
Automated cleanup of expired records

Access Controls¶

Role-based access to audit information
Immutable audit log entries
Tamper-evident logging mechanisms
Comprehensive access logging

Section sources - apps/shared/models/history.py - apps/shared/models/action_log.py - apps/service/routes/history.py

Customization and Automation¶

The decision management system provides extensive customization capabilities to adapt to specific organizational needs and automate routine processes.

Rule Engine Configuration¶

Business Rule Definition¶

Rules can be defined using a combination of configuration files, database-stored rules, and programmatic rule definitions.

Rule Priority and Conflict Resolution¶

Hierarchical rule evaluation with explicit conflict resolution strategies and fallback mechanisms.

Testing and Validation¶

Rule testing frameworks and simulation environments for validating rule behavior before deployment.

Automated Workflow Patterns¶

Template-Based Workflows¶

Predefined workflow templates for common decision scenarios with parameterized customization points.

Conditional Automation¶

Complex conditional logic for automating decisions based on multiple criteria and external system inputs.

Integration Points¶

REST APIs, webhooks, and message queue integrations for connecting with external systems and services.

Custom Extension Points¶

Plugin Architecture¶

Extensible plugin system for adding custom decision logic, notification handlers, and integration adapters.

Custom Validators¶

Pluggable validation frameworks for implementing organization-specific validation rules.

Reporting Extensions¶

Custom report generators and dashboard widgets for specialized analytics needs.

Section sources - apps/service/core/decision.py - apps/service/core/types.py

Error Handling and Conflict Resolution¶

The decision management system implements comprehensive error handling and conflict resolution mechanisms to ensure reliability and consistency.

Error Categories and Handling¶

Processing Errors¶

Network timeouts during external API calls
File processing failures for unsupported formats
Memory exhaustion during large batch operations

Business Logic Errors¶

Invalid state transitions
Permission violations
Rule conflicts and ambiguities

Data Integrity Errors¶

Concurrent modification conflicts
Referential integrity violations
Schema migration failures

Conflict Resolution Strategies¶

Version Control¶

Optimistic locking with version numbers to detect and resolve concurrent modifications.

Merge Strategies¶

Configurable merge strategies for conflicting decisions, including last-writer-wins, majority voting, and manual resolution.

Rollback Procedures¶

Automatic rollback capabilities for failed operations with detailed error reporting and recovery guidance.

Monitoring and Alerting¶

Real-time error rate monitoring
Automated alerting for critical failures
Performance degradation detection
Capacity planning alerts

Section sources - apps/service/core/decision.py

Performance Considerations¶

The decision management system is designed for high-throughput processing while maintaining responsiveness and resource efficiency.

Database Optimization¶

Query Optimization¶

Indexed queries for frequently accessed decision attributes
Connection pooling for concurrent request handling
Read replicas for reporting and analytics queries

Storage Efficiency¶

Compressed audit trail storage
Partitioned tables for time-based data access patterns
Archive strategies for historical data

Caching Strategies¶

Multi-Level Caching¶

In-memory caching for frequently accessed decision templates
Distributed caching for shared configuration and rules
CDN caching for static decision artifacts

Cache Invalidation¶

Event-driven cache invalidation for real-time consistency
TTL-based expiration for stale data prevention
Cache warming strategies for predictable performance

Scaling Considerations¶

Horizontal Scaling¶

Stateless service design for easy horizontal scaling
Load balancing across multiple decision processing instances
Database sharding for large-scale deployments

Resource Management¶

Dynamic resource allocation based on workload patterns
Graceful degradation under high load conditions
Resource cleanup and garbage collection optimization

Troubleshooting Guide¶

Common Issues and Solutions¶

Decision Processing Failures¶

Check system logs for specific error messages
Verify external service connectivity and authentication
Validate input data format and completeness
Review business rule configurations for conflicts

Performance Degradation¶

Monitor database query performance and indexes
Check memory usage and garbage collection patterns
Review network latency for external service calls
Analyze concurrent request patterns and bottlenecks

Notification Delivery Issues¶

Verify notification service configuration and credentials
Check email delivery logs and spam filtering
Validate recipient contact information and preferences
Review notification queue status and retry policies

Diagnostic Tools¶

Health Checks¶

System health monitoring endpoints
Dependency service availability checks
Performance metric collection and reporting

Debugging Utilities¶

Decision processing trace logging
Audit trail inspection tools
Performance profiling utilities

Recovery Procedures¶

Data Recovery¶

Backup restoration procedures for corrupted decision data
Audit trail reconstruction from distributed logs
Consistency verification and repair tools

Service Recovery¶

Graceful shutdown and restart procedures
Circuit breaker activation for failing dependencies
Emergency mode operation with reduced functionality

Section sources - apps/service/routes/decisions.py - apps/service/routes/history.py

Conclusion¶

Nexo's decision management system provides a comprehensive, scalable, and flexible framework for managing content classification decisions through automated and manual workflows. The system's modular architecture, extensive customization capabilities, and robust error handling make it suitable for organizations of all sizes with varying content processing requirements.

Key strengths of the system include its comprehensive audit trail capabilities, flexible rule engine, scalable bulk processing, and seamless integration with notification systems. The system's design emphasizes maintainability, extensibility, and compliance, making it well-suited for regulated industries and complex organizational workflows.

Future enhancements could include advanced machine learning integration for improved automated decisions, enhanced visualization tools for decision analytics, and expanded integration capabilities with external content management systems.