major updates

.kiro/steering/architecture-patterns.md

@@ -0,0 +1,167 @@
+# FlowRunner Architecture Patterns
+
+## Core Architectural Principles
+
+### Separation of Concerns
+- **Presentation Layer**: HTTP handlers and CLI commands
+- **Business Logic**: Flow execution and management
+- **Data Layer**: Storage abstractions and implementations
+- **Infrastructure**: Configuration, logging, and external integrations
+
+### Dependency Injection
+```go
+type FlowService struct {
+    storage   Storage
+    executor  Executor
+    logger    Logger
+    validator Validator
+}
+
+func NewFlowService(storage Storage, executor Executor, logger Logger, validator Validator) *FlowService {
+    return &FlowService{
+        storage:   storage,
+        executor:  executor,
+        logger:    logger,
+        validator: validator,
+    }
+}
+```
+
+## Storage Abstraction Pattern
+
+### Interface Definition
+```go
+type Storage interface {
+    CreateFlow(ctx context.Context, flow *Flow) error
+    GetFlow(ctx context.Context, id string) (*Flow, error)
+    UpdateFlow(ctx context.Context, flow *Flow) error
+    DeleteFlow(ctx context.Context, id string) error
+    ListFlows(ctx context.Context, accountID string) ([]*Flow, error)
+}
+```
+
+### Implementation Strategy
+- Implement separate packages for each storage backend
+- Use factory pattern for storage initialization
+- Implement proper connection management and pooling
+- Handle storage-specific errors consistently
+
+## Node Registry Pattern
+
+### Plugin Architecture
+```go
+type Node interface {
+    Execute(ctx context.Context, input map[string]interface{}) (map[string]interface{}, error)
+    Validate(params map[string]interface{}) error
+    GetType() string
+}
+
+type NodeRegistry struct {
+    nodes map[string]func() Node
+}
+
+func (r *NodeRegistry) Register(nodeType string, factory func() Node) {
+    r.nodes[nodeType] = factory
+}
+```
+
+### Node Implementation
+- Each node type implements the Node interface
+- Use factory functions for node creation
+- Implement proper parameter validation
+- Handle node-specific errors gracefully##
+ Flow Execution Pattern
+
+### Execution Context
+```go
+type ExecutionContext struct {
+    FlowID      string
+    ExecutionID string
+    AccountID   string
+    Input       map[string]interface{}
+    Secrets     map[string]string
+    Logger      Logger
+    Cancel      context.CancelFunc
+}
+```
+
+### State Management
+- Track execution state throughout flow lifecycle
+- Implement proper cleanup on cancellation
+- Store intermediate results for debugging
+- Handle concurrent node execution safely
+
+## Configuration Pattern
+
+### Hierarchical Configuration
+```go
+type Config struct {
+    Server   ServerConfig   `yaml:"server"`
+    Storage  StorageConfig  `yaml:"storage"`
+    Auth     AuthConfig     `yaml:"auth"`
+    Logging  LoggingConfig  `yaml:"logging"`
+}
+```
+
+### Configuration Sources
+1. Default values in code
+2. Configuration file (YAML)
+3. Environment variables
+4. Command-line flags
+
+Priority: CLI flags > Environment > Config file > Defaults
+
+## Error Handling Patterns
+
+### Structured Errors
+```go
+type FlowError struct {
+    Code      string `json:"code"`
+    Message   string `json:"message"`
+    Details   string `json:"details,omitempty"`
+    Cause     error  `json:"-"`
+}
+
+func (e *FlowError) Error() string {
+    return fmt.Sprintf("%s: %s", e.Code, e.Message)
+}
+```
+
+### Error Categories
+- **ValidationError**: Input validation failures
+- **ExecutionError**: Runtime execution failures
+- **StorageError**: Data persistence failures
+- **AuthError**: Authentication/authorization failures
+
+## HTTP API Patterns
+
+### Handler Structure
+```go
+type FlowHandler struct {
+    service *FlowService
+    logger  Logger
+}
+
+func (h *FlowHandler) CreateFlow(w http.ResponseWriter, r *http.Request) {
+    var req CreateFlowRequest
+    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+        h.writeError(w, http.StatusBadRequest, "invalid request body")
+        return
+    }
+
+    flow, err := h.service.CreateFlow(r.Context(), &req)
+    if err != nil {
+        h.handleServiceError(w, err)
+        return
+    }
+
+    h.writeJSON(w, http.StatusCreated, flow)
+}
+```
+
+### Middleware Chain
+- Authentication middleware
+- Logging middleware
+- CORS middleware
+- Rate limiting middleware
+- Request validation middleware

.kiro/steering/development-guidelines.md

@@ -0,0 +1,171 @@
+# FlowRunner Development Guidelines
+
+## Code Style and Standards
+
+### Go Conventions
+- Follow standard Go formatting with `gofmt`
+- Use `golint` and `go vet` for code quality
+- Implement proper error handling with wrapped errors
+- Use context.Context for cancellation and timeouts
+- Follow Go naming conventions (exported vs unexported)
+
+### Package Structure
+- Keep packages focused and cohesive
+- Avoid circular dependencies
+- Use interfaces for abstraction and testability
+- Implement dependency injection patterns
+- Separate business logic from infrastructure concerns
+
+### Error Handling
+```go
+// Preferred error handling pattern
+if err != nil {
+    return fmt.Errorf("failed to execute flow %s: %w", flowID, err)
+}
+```
+
+## Testing Standards
+
+### Unit Testing
+- Test coverage should be >80% for core packages
+- Use table-driven tests for multiple scenarios
+- Mock external dependencies using interfaces
+- Test both success and error paths
+- Use testify/assert for cleaner assertions
+
+### Integration Testing
+- Test storage backend implementations
+- Verify HTTP API endpoints with real requests
+- Test flow execution end-to-end
+- Use test containers for database testing
+
+### Test Organization
+```go
+func TestFlowExecution(t *testing.T) {
+    tests := []struct {
+        name     string
+        flow     *Flow
+        input    map[string]interface{}
+        expected ExecutionResult
+        wantErr  bool
+    }{
+        // test cases
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            // test implementation
+        })
+    }
+}
+```
+
+## API Design Principles
+
+### RESTful Design
+- Use proper HTTP methods (GET, POST, PUT, DELETE)
+- Follow consistent URL patterns: `/api/v1/resource/{id}`
+- Return appropriate HTTP status codes
+- Use JSON for request/response bodies
+- Implement proper error responses with details
+
+### Authentication & Authorization
+- Use JWT tokens for stateless authentication
+- Implement account-based isolation
+- Encrypt sensitive data in storage
+- Validate all inputs and sanitize outputs
+- Follow security best practices
+
+### Versioning
+- Use URL versioning: `/api/v1/`
+- Maintain backward compatibility within major versions
+- Document breaking changes clearly
+- Provide migration guides for major version updates
+
+## Configuration Management
+
+### Environment Variables
+- Use clear, prefixed environment variable names: `FLOWRUNNER_*`
+- Provide sensible defaults where possible
+- Document all configuration options
+- Support multiple configuration sources (env, file, flags)
+
+### Secrets Management
+- Never commit secrets to version control
+- Use encrypted storage for sensitive data
+- Implement proper key rotation mechanisms
+- Audit access to sensitive configuration
+
+## Performance Guidelines
+
+### Execution Efficiency
+- Use goroutines for concurrent node execution
+- Implement proper context cancellation
+- Avoid blocking operations in hot paths
+- Use connection pooling for database access
+- Implement caching where appropriate
+
+### Memory Management
+- Avoid memory leaks in long-running processes
+- Use streaming for large data processing
+- Implement proper cleanup in defer statements
+- Monitor memory usage in production
+
+## Logging and Monitoring
+
+### Structured Logging
+```go
+log.WithFields(log.Fields{
+    "flow_id":      flowID,
+    "execution_id": execID,
+    "node_id":      nodeID,
+}).Info("Node execution completed")
+```
+
+### Metrics and Observability
+- Track execution times and success rates
+- Monitor resource usage (CPU, memory, connections)
+- Implement health check endpoints
+- Use distributed tracing for complex flows
+
+## Documentation Standards
+
+### Code Documentation
+- Document all exported functions and types
+- Include usage examples in godoc comments
+- Explain complex algorithms and business logic
+- Document configuration options and defaults
+
+### API Documentation
+- Maintain OpenAPI/Swagger specifications
+- Provide request/response examples
+- Document error codes and messages
+- Include authentication requirements
+
+## Security Considerations
+
+### Input Validation
+- Validate all user inputs
+- Sanitize data before storage
+- Implement rate limiting on API endpoints
+- Use parameterized queries for database access
+
+### Data Protection
+- Encrypt sensitive data at rest
+- Use TLS for all network communication
+- Implement proper session management
+- Follow OWASP security guidelines
+
+## Deployment and Operations
+
+### Build Process
+- Use multi-stage Docker builds
+- Implement proper dependency management
+- Create reproducible builds
+- Use semantic versioning for releases
+
+### Monitoring and Alerting
+- Implement health checks and readiness probes
+- Monitor key business metrics
+- Set up alerting for critical failures
+- Maintain operational runbooks