Temporal Workers & Workflows
Relevant source files
The following files were used as context for generating this wiki page:
Temporal Workers and Workflows provide the asynchronous execution engine for the NeXifyAI platform. This system handles long-running business processes, agent orchestrations, and deployment pipelines using a reliable, stateful workflow management layer. It ensures that every task follows a defined lifecycle with built-in recovery patterns, circuit breakers, and Dead Letter Queues (DLQ) to prevent cascade failures.
The platform utilizes the Python Temporal SDK to implement these workers, which are routed to handle specific agent mesh activities and governance gates. Every decision, error, and insight processed through these workflows feeds back into the central Qdrant-based Brain for organizational persistence and learning.
Architecture & System Integration
The Temporal layer sits between the FastAPI REST server and the autonomous agent runtime. It manages the transition of tasks through various states—from creation to final archival—while enforcing quality gates.
The diagram shows the flow from API requests into the Temporal Worker, which orchestrates calls to the Brain, Agent Runtime, and Database while being protected by Governance mechanisms.
Sources: ARCHITECTURE.md:10-25, SETUP.md:95-105
Key Components
| Component | Responsibility | Technology |
|---|---|---|
| Temporal Workers | Executes workflow logic and activities | Python Temporal SDK |
| Workflows | Defines the state machine and sequence of tasks | Python |
| Activities | Atomic, idempotent units of work (e.g., DB writes, API calls) | Python |
| Governance Gate | Validates runtime health before workflow execution | Governance Bootstrap |
| Circuit Breaker | Prevents resource exhaustion during failures | Python Logic |
Sources: ARCHITECTURE.md:15-20, ARCHITECTURE.md:50-55
Order Workflow Lifecycle
The order-workflow-specialist manages the production pipeline, ensuring that no work occurs without a tracked order. The workflow follows a strict state machine to maintain visibility and auditability.
The state machine defines the transitions an order must take from creation to completion, including error handling and rework loops.
Sources: services/api/agents/brain_agents/order-workflow-specialist.md:21-25
Priority Routing Matrix
The workflow engine routes tasks based on priority levels, defining execution authority and escalation timeouts.
| Priority | Actor | Reviewer | Timeout | Escalation |
|---|---|---|---|---|
| P0 | CEO + Expert | CEO | 15 min | Immediate All-Stakeholders |
| P1 | Domain Expert | Senior QA | 60 min | CEO after 3 failures |
| P2 | Expert (Auto) | Review Agent | 4 hours | Project Manager |
| P3 | Scheduled | Review Agent | 24 hours | Next Business Day |
Sources: services/api/agents/brain_agents/order-workflow-specialist.md:27-35
Quality Gate Enforcement
Workflows are gated by the senior-quality-auditor. A workflow cannot reach the APPROVED or DEPLOYED state without passing seven mandatory quality gates.
The Seven Gates
- Documentation: Architecture specs, API docs, and SOP references must exist.
- Testing: Unit tests must meet coverage thresholds (P0 ≥ 80%).
- Security: Secrets must be in the vault; zero-trust and RBAC must be enforced.
- Architecture: Compliance with the 12-System model.
- Performance: Latency checks (<200ms p95 for APIs).
- Workflow: Verified context enrichment and expert matching.
- Agent Quality: Agent profile length (≥4000 chars) and heartbeat configuration.
Sources: services/api/agents/brain_agents/senior-quality-auditor.md:20-75, services/api/agents/brain_agents/order-workflow-specialist.md:46-56
The sequence diagram illustrates the interaction between a running workflow, the quality auditor, and the persistent Brain knowledge base.
Sources: services/api/agents/brain_agents/senior-quality-auditor.md:120-135
Error Handling & Recovery
Workflows implement standard recovery patterns to handle transient failures and blocking dependencies.
- Stuck Orders: Orders that exceed their priority timeout are automatically escalated to a supervisor or reassigned.
- Agent Unavailability: The system retries twice before triggering the matching algorithm to find a new expert agent.
- Brain Failure: Workflows fallback to keyword routing and queue Brain writes if the Qdrant service is unavailable.
- Dead Letter Queue (DLQ): Captures failed operations for manual replay or automated analysis.
Sources: ARCHITECTURE.md:58-65, services/api/agents/brain_agents/order-workflow-specialist.md:79-90
Conclusion
Temporal Workers and Workflows act as the reliable backbone of the NeXifyAI platform. By integrating governance gates, stateful order management, and autonomous agent orchestration, the system ensures that complex enterprise AI tasks are executed with high reliability and full auditability. Every workflow execution contributes to the platform's collective intelligence by persisting results and lessons learned back into the Brain.