generated from coulomb/repo-seed
95 lines
4.0 KiB
Markdown
95 lines
4.0 KiB
Markdown
# 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
|
|
|
|
---
|
|
|
|
## Related / Overlapping Repositories
|
|
|
|
- `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
|
|
|
|
---
|
|
|
|
## 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
|