flow-core

Shared types, configuration, themes, errors, and events used across all Flow crates.

What it does

flow-core is the foundation crate that every other crate depends on. It defines the common language that all parts of Flow use to communicate. Think of it as the dictionary and grammar rules that everyone agrees on.

It contains:

• Types: Feature, Task, Session - the data structures everything works with
• Configuration: Both workflow config (~/.config/flow/config.toml) and agent monitoring config
• Themes: 7 color themes with ANSI (terminal) and CSS (web) representations
• Errors: A unified error type with 14 variants for everything that can go wrong
• Events: Event types for real-time updates between components

Architecture

flow-core/
├── lib.rs        - Module exports and Result type alias
├── config.rs     - Workflow config (projects_dir, state_dir, default_branch)
├── agent.rs      - AgentConfig (port, theme, concurrency, paths)
├── feature.rs    - Feature, FeatureStats, FeatureGraphNode, CreateFeatureInput
├── task.rs       - Task, SessionListItem, SessionMeta, TaskWithSession
├── theme.rs      - 7 themes with ANSI + CSS color definitions
├── event.rs      - FlowEvent enum for SSE/WebSocket broadcasting
├── error.rs      - FlowError with 14 variants
├── state.rs      - Shared state types
└── project.rs    - Project metadata types

Key Types

Feature (SQLite-backed)

pub struct Feature {
    pub id: i64,
    pub priority: i32,       // Lower = more important
    pub category: String,    // e.g., "Backend", "Frontend"
    pub name: String,
    pub description: String,
    pub steps: Vec<String>,  // Implementation checklist
    pub passes: bool,        // Test status
    pub in_progress: bool,   // Currently claimed by an agent
    pub dependencies: Vec<i64>, // Feature IDs this depends on
    pub created_at: Option<String>,
    pub updated_at: Option<String>,
}

Task (JSON file-based)

pub struct Task {
    pub id: String,
    pub subject: String,
    pub description: String,
    pub active_form: String,  // What the agent is currently doing
    pub status: String,       // "pending", "in_progress", "completed"
    pub owner: String,        // "claude", "codex", "gemini"
    pub blocks: Vec<String>,
    pub blocked_by: Vec<String>,
}

Theme

pub enum Theme {
    Default,       // Dark cyan on slate
    Claude,        // Anthropic terracotta on cream
    Twitter,       // X blue on black
    NeoBrutalism,  // Bold yellow/pink on white
    RetroArcade,   // Neon green on black
    Aurora,        // Purple/teal gradient
    Business,      // Navy on white
}

Each theme provides both ANSI 256-color codes (for the TUI) and CSS hex values (for the web UI).

FlowError

pub enum FlowError {
    Io(std::io::Error),
    ConfigParse(toml::de::Error),
    Git(String),
    Tmux(String),
    ProjectNotFound(String),
    Database(String),
    NotFound(String),
    BadRequest(String),
    Conflict(String),
    Parse(String),
    Timeout(String),
    CycleDetected(String),
    Json(serde_json::Error),
    Server(String),
}

Usage

use flow_core::{
    Feature, Task, Config, AgentConfig,
    Theme, ThemeColors, FlowEvent, FlowError, Result,
};

// Load workflow configuration
let config = Config::load()?;
println!("Projects dir: {}", config.projects_dir.display());

// Create agent monitoring config
let agent_config = AgentConfig::new()
    .with_port(3456)
    .with_theme(Theme::Aurora)
    .with_open_browser(true);

// Use theme colors
let theme = Theme::Aurora;
let colors = theme.colors();
println!("Primary CSS color: {}", colors.css_primary);
println!("Primary ANSI: {}", colors.primary.fg());

// Cycle through themes
let next = theme.next(); // Business

Configuration

Workflow Config (~/.config/flow/config.toml)

projects_dir = "~/Projects"
state_dir = "~/.local/state/flow"
default_base_branch = "main"

If the file doesn't exist, sensible defaults are used.

Agent Config (programmatic)

let config = AgentConfig::new()     // Defaults
    .with_port(3456)                // Web server port
    .with_theme(Theme::Default)     // Color theme
    .with_max_concurrency(5)        // Max parallel agents
    .with_open_browser(true);       // Auto-open browser

Testing

cargo test -p flow-core

Related Crates

Every crate in the workspace depends on flow-core:

• flow-db - Uses Feature, CreateFeatureInput, FlowError
• flow-resolver - Uses Feature, FlowError
• flow-server - Uses AgentConfig, Task, Theme, FlowEvent
• flow-tui - Uses Theme, ThemeColors
• flow-cli - Uses Config, AgentConfig, Theme

Back to main README