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

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

• 01-core-sdk - Core SDK fundamentals
• 02-dataflow - DataFlow framework
• 03-nexus - Nexus framework
• 04-kaizen - Kaizen framework
• 08-nodes-reference - Node reference
• 12-testing-strategies - Testing strategies

Support

For architecture decisions, invoke:

• framework-advisor - Framework selection and architecture
• ultrathink-analyst - Deep analysis for complex decisions
• requirements-analyst - Requirements breakdown
• pattern-expert - Pattern recommendations