SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.

One-liner

Event-driven task factory backbone using Temporal — defines ActivityDefinitions that spawn TaskInstances when triggered by cron schedules or domain events, with durable execution and PostgreSQL persistence.

Core Idea

Activity-core replaces ad-hoc cron jobs and Celery tasks with a durable Temporal-based workflow engine. An ActivityDefinition declares what triggers it (cron or event), how to resolve context, and what task templates to spawn. When triggered, a RunActivityWorkflow executes durably, creating TaskInstance records and run logs. Server crashes replay automatically from Temporal's event log.

In Scope

Domain model: ActivityDefinition, EventEnvelope, CronTriggerConfig, EventTriggerConfig, RunActivityWorkflow, TaskInstance
Trigger types: 5-field cron (with timezone, jitter, misfire policy) or event-based (EventEnvelope type + payload filters)
EventEnvelope normalization: standard internal event format for all inbound events
Context resolution: load definition from DB, resolve context sources, evaluate rules
Task spawning: generate TaskInstance records as child workflows/activities
Run logging: audit trail of activity executions, task creation, completion

Out of Scope

Temporal server hosting/operations (activity-core consumes Temporal SDK; infra is separate)
End-user task UI (TaskInstance records are created; presentation is a separate concern)
Event broker integration (upstream router delivers EventEnvelopes; activity-core receives them)
Synchronous request-response workflows (Temporal is async-first)

Relevant When

Need durable, time-triggered or event-triggered task generation with crash resilience
Want an audit trail of activity runs and spawned task instances
Replacing unreliable cron + Celery patterns with replay-safe Temporal workflows

Not Relevant When

Simple system cron jobs with no durability requirement
Synchronous request-response patterns
Existing Celery infrastructure is working (migration is non-trivial)

Current State

Status: concept → planning (pre-alpha)
Implementation: ~30% — domain model defined (EventEnvelope, ActivityDefinition, trigger configs); PostgreSQL schema planned; Temporal workflows.py + activities.py not yet scaffolded
Stability: unstable — models are valid but untested in real workflows
Usage: none yet; proto-planning phase

How It Fits

Upstream dependencies: Temporal (orchestration engine), PostgreSQL (persistence), ops-bridge (network tunnel to remote Temporal server)
Downstream consumers: Custodian State Hub tracks activity-core workstreams; tasks spawned feed into other systems
Often used with: kaizen-agentic (project scaffolding), the-custodian (workstream tracking), railiance (Temporal server may run on Railiance infrastructure)

Terminology

Preferred terms: ActivityDefinition, EventEnvelope, RunActivityWorkflow, TaskInstance, trigger, misfire policy
Also known as: "the task factory", "activity backbone"
Potentially confusing terms: "Activity" is a Temporal concept (a single executable step); "ActivityDefinition" is the app-level record that configures what gets spawned

the-custodian — tracks activity-core workstreams in State Hub (domain: custodian)
ops-bridge — provides network tunnel to remote Temporal server
railiance-cluster / railiance-platform — may host Temporal server

Provided Capabilities

type: data
title: Durable event-triggered task factory
description: Temporal-based workflow engine that spawns TaskInstance records on cron schedules or domain events with crash resilience and full replay — replaces ad-hoc cron/Celery patterns.
keywords: [temporal, workflow, task, cron, event, durable, taskfactory]

Getting Oriented

Start with: CLAUDE.md (session protocol, repo boundary), wiki/ActivityCorePlan_chtgpt.md (proto-architecture)
Key files / directories: src/activity_core/models.py (EventEnvelope, ActivityDefinition), workplans/ (roadmap), docker-compose.dev.yml (local Temporal + PostgreSQL)
Entry points: models.py is the current starting point; workflows.py does not yet exist

4.4 KiB Raw Blame History