| name | architecture-decisions |
| description | Architecture decision guides for Kailash SDK including framework selection (Core SDK vs DataFlow vs Nexus vs Kaizen), runtime selection (Async vs Sync), database selection (PostgreSQL vs SQLite), node selection, and test tier selection. Use when asking about 'which framework', 'choose framework', 'which runtime', 'which database', 'which node', 'architecture decision', 'when to use', 'Core SDK vs DataFlow', 'PostgreSQL vs SQLite', 'AsyncLocalRuntime vs LocalRuntime', or 'test tier selection'. |
Kailash Architecture Decisions
Decision guides for selecting the right frameworks, runtimes, databases, nodes, and testing strategies for your Kailash application.
Overview
Comprehensive decision guides for:
- Framework selection (Core SDK, DataFlow, Nexus, Kaizen)
- Runtime selection (AsyncLocalRuntime vs LocalRuntime)
- Database selection (PostgreSQL vs SQLite)
- Node selection for specific tasks
- Test tier selection (Unit, Integration, E2E)
Reference Documentation
Framework Selection
- decide-framework - Choose the right framework
- Core SDK: Custom workflows with full control
- DataFlow: Database-first applications
- Nexus: Multi-channel platforms
- Kaizen: AI agent systems
- When to use each
- Combining frameworks
Runtime Selection
- decide-runtime - AsyncLocalRuntime vs LocalRuntime
- Docker/FastAPI → AsyncLocalRuntime
- CLI/Scripts → LocalRuntime
- Performance implications
- Threading considerations
- Auto-detection with get_runtime()
Database Selection
- decide-database-postgresql-sqlite - PostgreSQL vs SQLite
- Production → PostgreSQL
- Development/Testing → SQLite
- Feature comparison
- Migration strategies
- Multi-database support
Node Selection
- decide-node-for-task - Choose the right node
- AI tasks → AI nodes
- API calls → API nodes
- Custom logic → PythonCodeNode
- Database → Database nodes or DataFlow
- File operations → File nodes
- Conditional logic → SwitchNode
Test Tier Selection
- decide-test-tier - Unit vs Integration vs E2E
- Tier 1: Unit tests (fast, mocking allowed)
- Tier 2: Integration tests (real infrastructure)
- Tier 3: End-to-end tests (full system)
- When to use each tier
- Coverage targets
Key Decision Frameworks
Framework Selection Matrix
| Need | Framework | Why |
|---|
| Custom workflows | Core SDK | Full control, 110+ nodes |
| Database CRUD | DataFlow | Auto-generated nodes |
| Multi-channel API | Nexus | API + CLI + MCP instantly |
| AI agents | Kaizen | Signature-based agents |
| All of above | Combine them | They work together |
Runtime Selection Flow
Are you deploying to Docker/FastAPI/Kubernetes?
├─ YES → AsyncLocalRuntime (async-first, no threads)
└─ NO → Is this a CLI/script?
├─ YES → LocalRuntime (sync execution)
└─ NO → Use get_runtime() for auto-detection
Database Selection Flow
What's your use case?
├─ Production deployment?
│ └─ YES → PostgreSQL (scalable, enterprise)
├─ Development/testing?
│ └─ YES → SQLite (simple, fast setup)
└─ High concurrency?
└─ YES → PostgreSQL (better concurrency)
Node Selection Flow
What task are you doing?
├─ Custom Python logic → PythonCodeNode
├─ LLM/AI tasks → LLMNode, OpenAINode, AnthropicNode
├─ Database operations → DataFlow auto-generated nodes
├─ HTTP API calls → APICallNode
├─ File reading → FileReaderNode
├─ Conditional routing → SwitchNode
└─ Not sure? → Check nodes-quick-index
Test Tier Flow
What are you testing?
├─ Individual function → Tier 1 (Unit)
├─ Workflow execution → Tier 2 (Integration)
├─ Complete user flow → Tier 3 (E2E)
└─ All of above → Use all tiers
Critical Decision Rules
Framework Decisions
- ✅ Use Core SDK for custom workflows
- ✅ Use DataFlow for database operations (don't use SQLAlchemy/Django ORM)
- ✅ Use Nexus for multi-channel platforms (don't use FastAPI directly)
- ✅ Use Kaizen for AI agents (don't build from scratch)
- ✅ Combine frameworks as needed
- ❌ NEVER use ORM when DataFlow can generate nodes
- ❌ NEVER build API/CLI/MCP manually when Nexus can do it
- ❌ NEVER skip framework evaluation
Runtime Decisions
- ✅ Docker/FastAPI → AsyncLocalRuntime (mandatory)
- ✅ CLI/Scripts → LocalRuntime
- ✅ Use get_runtime() when unsure
- ❌ NEVER use LocalRuntime in Docker (causes hangs)
- ❌ NEVER mix runtimes in same application
Database Decisions
- ✅ Production → PostgreSQL
- ✅ Development → SQLite (for speed)
- ✅ Testing → SQLite in Docker (for isolation)
- ✅ Multi-instance → One DataFlow per database
- ❌ NEVER use SQLite for production high-concurrency
- ❌ NEVER skip connection pooling config
When to Use This Skill
Use this skill when you need to:
- Choose between Core SDK, DataFlow, Nexus, or Kaizen
- Select AsyncLocalRuntime vs LocalRuntime
- Decide between PostgreSQL and SQLite
- Find the right node for a task
- Determine test tier for a test case
- Make architecture decisions
- Understand trade-offs between options
Decision Templates
Starting a New Project
1. What's the primary use case?
- Database CRUD → Start with DataFlow
- Multi-channel API → Start with Nexus
- AI agents → Start with Kaizen
- Custom workflows → Start with Core SDK
2. What's the deployment target?
- Docker/K8s → Use AsyncLocalRuntime
- CLI tool → Use LocalRuntime
3. What's the database?
- Production → PostgreSQL
- Dev/Test → SQLite
4. How to test?
- Tier 1: Fast unit tests
- Tier 2: Real infrastructure integration
- Tier 3: Full system E2E
Related Skills
Support
For architecture decisions, invoke:
framework-advisor - Framework selection and architectureultrathink-analyst - Deep analysis for complex decisionsrequirements-analyst - Requirements breakdownpattern-expert - Pattern recommendations
