System Overview
Infinitic consists of four main components:Clients
Application code that starts and interacts with workflows
Workers
Runtime components that execute workflows and services
Apache Pulsar
Event streaming platform for reliable message delivery
Storage
State persistence for workflows (Redis, Postgres, MySQL)
Core Components
1. Clients
Clients are application code that interacts with Infinitic:- Start workflows with parameters and tags
- Send signals to running workflows via channels
- Query status of workflows and tasks
- Manage workflows (cancel, retry, complete timers)
infinitic-client/src/main/kotlin/io/infinitic/clients/InfiniticClient.kt
2. Workers
Workers are long-running processes that execute workflows and services. Each worker can run multiple components:Service Executor
Executes service methods when called by workflows:Workflow Executor
Executes workflow tasks (the workflow code itself):Workflow State Engine
Manages workflow state, handles events, and dispatches tasks:- Stores workflow state in configured storage (Redis/Postgres/MySQL)
- Processes events (task completed, task failed, timer completed)
- Dispatches new workflow tasks
- Manages workflow lifecycle
Tag Engines
Manage tags for workflows and services:- Map tags to workflow/service IDs
- Enable lookup by custom identifiers
- Support multiple IDs per tag
infinitic-worker/src/main/kotlin/io/infinitic/workers/InfiniticWorker.kt
3. Apache Pulsar
Pulsar provides reliable, ordered message delivery:- Topics per entity: Separate topics for each service/workflow
- Guaranteed delivery: Messages are persisted and replayed if needed
- Ordered processing: Messages with the same key are processed in order
- Scalability: Distribute load across consumers
4. Storage Layer
State persistence for workflows: Key-Value Storage:- Workflow state by workflow ID
- Tag mappings (tag → workflow IDs)
- Serialized using efficient binary format
- Redis: Fast, in-memory storage
- PostgreSQL: Relational database with ACID guarantees
- MySQL: Popular relational database
- In-Memory: For testing only (not persistent)
infinitic-storage/src/main/kotlin/io/infinitic/storage/
Message Flow
Starting a Workflow
Service Call from Workflow
Workflow State Management
Workflows maintain state across service calls:State Components
- Workflow Properties: Current values of workflow fields
- Method State: Running methods and their local variables
- Step History: Completed steps and their results
- Running Commands: In-flight service calls and child workflows
- Timers: Active timers and their completion times
State Persistence
Frominfinitic-workflow-engine:
- Serialized efficiently using binary format
- Compressed optionally to reduce storage size
- Cached optionally using Caffeine cache
- Logged for debugging via LoggedWorkflowStateStorage
infinitic-workflow-engine/src/main/kotlin/io/infinitic/workflows/engine/storage/
Execution Guarantees
Durability
Workflows survive failures through:- State Persistence: Workflow state saved after each step
- Message Durability: Pulsar persists messages until acknowledged
- Replay from State: Workers replay workflow from saved state
- Idempotent Operations: Duplicate messages handled safely
Ordering
FromInfiniticWorker.kt, messages are processed:
- With key: Messages with same key processed sequentially
- Without key: Messages processed concurrently up to concurrency limit
- Workflow state updates are sequential
- Service tasks can be parallel
- Tag updates are consistent
At-Least-Once Delivery
All operations have at-least-once semantics:- Messages may be delivered multiple times
- Services should be idempotent when possible
- Workflow replay is deterministic (same inputs → same outputs)
Scalability
Horizontal Scaling
Workers:- Add more worker instances
- Each consumes from same topics
- Load distributed automatically by Pulsar
- Add more brokers for message throughput
- Add more bookies for storage throughput
Vertical Scaling
Concurrency:Modules Overview
Infinitic codebase is organized into modules:| Module | Purpose | Location |
|---|---|---|
infinitic-common | Shared data structures and interfaces | Core types, messages |
infinitic-client | Client API and implementation | InfiniticClient |
infinitic-worker | Worker runtime and configuration | InfiniticWorker |
infinitic-storage | Storage abstraction and implementations | Redis, Postgres, MySQL |
infinitic-cache | Caching layer for storage | Caffeine cache |
infinitic-transport | Transport abstraction | Message routing |
infinitic-transport-pulsar | Pulsar implementation | Pulsar topics, producers |
infinitic-workflow-engine | Workflow state management | State engine, handlers |
infinitic-task-executor | Service execution | Task execution logic |
infinitic-task-tag | Service tag management | Tag engine |
infinitic-workflow-tag | Workflow tag management | Tag engine |
Deployment Patterns
Monolithic Deployment
Single worker running all components:Separated Deployment
Different workers for different responsibilities:Kubernetes Deployment
Observability
Cloud Events
Infinitic emits Cloud Events for all operations:Logging
FromInfiniticWorker.kt:144-176, workers log in-flight message counts on shutdown:
Metrics
Integrate with monitoring systems:- Message throughput
- Task execution time
- Workflow duration
- Error rates
- Queue depths
Best Practices
Separate Concerns
Run executors and engines in different workers for better scaling
Use Caching
Enable state caching to reduce storage load
Monitor Queues
Track Pulsar queue depths to detect bottlenecks
Plan for Failure
Design workflows to be resilient to service failures
Next Steps
Workflows
Learn about workflow patterns and features
Services
Implement services for your business logic
Workers
Deploy and configure workers
Clients
Interact with workflows from your applications