🧩 Elements Catalog
Workflow building blocks with REQUIRES/PRODUCES contracts
🔄 Workflow Diagrams
Visual schemas showing element connections and data flow
🤖 Telegram Commands
Bot commands and what they trigger
🏗️ Architecture Overview
Four-Tier Service Pattern and Data Flow
Four-Tier Element Pattern
graph TB
subgraph "Tier 1: Interface"
I[Protocol/Interface]
end
subgraph "Tier 2: Testing"
S[Stub Implementation]
end
subgraph "Tier 3: Business Logic"
B[Impl - Pure Logic]
end
subgraph "Tier 4: Observability"
L[Logged Wrapper]
end
I --> S
I --> B
B --> L
style I fill:#e1f5fe
style S fill:#fff3e0
style B fill:#e8f5e9
style L fill:#fce4ec
Tier 1
Interface (Protocol) — Defines REQUIRES/PRODUCES contract
Tier 2
Stub — Mock implementation for testing
Tier 3
Impl — Pure business logic, no side effects
Tier 4
Logged — Adds timing, metrics, observability
Data Flow Architecture
graph LR
subgraph Input
U[User Data]
end
subgraph "Core Computation"
N[Natal Chart]
T[Transits]
end
subgraph "AI Processing"
P[Persona]
G[Guidance]
end
subgraph Output
R[Report]
M[Markdown]
end
U --> N
N --> T
N --> P
T --> G
P --> G
G --> R
G --> M
style U fill:#bbdefb
style N fill:#c8e6c9
style T fill:#c8e6c9
style P fill:#fff9c4
style G fill:#fff9c4
style R fill:#ffccbc
style M fill:#ffccbc
Key Concepts
WorkflowState
Immutable state container. Elements read from and write to state.data dictionary.
REQUIRES
Set of state keys the element needs to execute. Validated before run.
PRODUCES
Set of state keys the element will add. Used for dependency graph.
Workflow JSON
Declarative workflow definition with elements, config, and connections.