Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
460 lines (346 loc) · 11.9 KB

ARCHITECTURE.md

File metadata and controls

460 lines (346 loc) · 11.9 KB
Raw

Origin Workflow CLI - Architecture Design

Overview

Transform the Origin Workflow from 15+ manual commands into a single, intelligent CLI app with a Claude-like interactive experience.

Design Principles

  1. Single Entry Point: One command (origin-workflow) with intelligent subcommands
  2. Progressive Disclosure: Simple by default, powerful when needed
  3. Guided Workflows: Step-by-step assistance for complex operations
  4. Visual Feedback: Rich terminal UI with progress indicators
  5. Safety First: Confirmations for dangerous operations, dry-run modes
  6. Fast & Responsive: Sub-2-second response times for common operations

Project Structure

cli/
├── bin/
│   └── origin-workflow.js          # Main executable (global CLI entry point)
├── src/
│   ├── commands/
│   │   ├── daily.js                # Daily workflow orchestration
│   │   ├── capture.js              # Unified content capture
│   │   ├── health.js               # System health dashboard
│   │   ├── config.js               # Configuration management
│   │   ├── process.js              # Data processing workflows
│   │   └── index.js                # Command registry
│   ├── ui/
│   │   ├── prompts.js              # Reusable interactive prompts
│   │   ├── progress.js             # Progress indicators & spinners
│   │   ├── tables.js               # Data display tables
│   │   └── themes.js               # Color schemes & styling
│   ├── utils/
│   │   ├── logger.js               # Logging utilities
│   │   ├── validator.js            # Input validation
│   │   ├── files.js                # File system helpers
│   │   └── system.js               # System state management
│   └── index.js                    # Main CLI orchestrator
├── config/
│   └── defaults.json               # Default CLI configuration
└── package.json                    # CLI dependencies

Technology Stack

  • Node.js: Runtime (v14+)
  • inquirer.js: Interactive prompts
  • chalk: Terminal styling
  • ora: Elegant spinners
  • cli-table3: Beautiful tables
  • figlet: ASCII art for branding
  • boxen: Message boxes
  • commander: Command-line parsing

Command Structure

Primary Commands

# Daily workflow - Smart orchestration
origin-workflow daily [options]

# Content capture - Unified interface
origin-workflow capture [options]

# System health - Visual dashboard
origin-workflow health [options]

# Configuration - Interactive wizard
origin-workflow config [options]

# Data processing - Batch operations
origin-workflow process [options]

Command Options

All commands support:

  • --help: Show command-specific help
  • --verbose: Detailed output
  • --dry-run: Preview without executing
  • --yes: Skip confirmations (automation mode)

Workflow Implementations

1. Daily Workflow (origin-workflow daily)

Current Manual Process:

node scripts/health_check.js --verbose
node automation/normalize.js
node automation/issue_generator.js
node agent/harness.js --mode local
cat daily/daily.md

New Interactive Experience:

$ origin-workflow daily

┌─────────────────────────────────────────┐
│  Origin Workflow - Daily Planning       │
└─────────────────────────────────────────┘

✓ System health check passed
✓ Processing 47 items from reading queue
✓ Analyzing your schedule and energy levels

📊 Quick Stats:
  • High Priority: 12 items
  • Medium Priority: 23 items
  • Low Priority: 12 items
  • Estimated work time: 3.5 hours

⚡ Energy Profile: High energy (9:00 AM - 12:00 PM)

? Ready to generate today's plan? (Y/n)

⏳ Generating plan...

✨ Daily plan ready!

📅 Today's Focus: 6 tasks | 99 minutes | 2 breaks

Would you like to:
  ❯ View the plan
    Edit the plan
    Export to calendar
    Start work timer

2. Capture Workflow (origin-workflow capture)

Current Manual Process:

node scripts/capture.js --title "..." --url "..." --tags "..."
# OR
curl -X POST http://localhost:3000/capture -d '{...}'

New Interactive Experience:

$ origin-workflow capture

? What would you like to capture?
  ❯ URL/Article
    Quick note
    File/Document
    Twitter thread
    Research paper

? Paste the URL: https://example.com/article

⏳ Analyzing content...

✓ Title: "The Future of AI Development"
✓ Reading time: ~12 minutes
✓ Content type: Blog post

? Suggested tags: #ai #development #future

? Add custom tags? productivity

? Priority level? (Use arrow keys)
  ❯ Medium
    High
    Low

✓ Captured! Added to reading queue (position #23)

What's next?
  ❯ Capture another item
    View reading queue
    Process queue now
    Done

3. Health Dashboard (origin-workflow health)

Current Manual Process:

node scripts/health_check.js --verbose

New Interactive Experience:

$ origin-workflow health

┌──────────────────────────────────────────────────┐
│  System Health Dashboard                         │
└──────────────────────────────────────────────────┘

Overall Status: ✅ Healthy

📊 Component Status:
┌──────────────────┬──────────┬───────────────────┐
│ Component        │ Status   │ Details           │
├──────────────────┼──────────┼───────────────────┤
│ Status File      │ ✅ Pass  │ Updated 5 min ago │
│ Directory Struct │ ✅ Pass  │ All dirs present  │
│ File Integrity   │ ✅ Pass  │ All files valid   │
│ Configuration    │ ⚠️  Warn │ 1 file missing    │
│ Data Quality     │ ✅ Pass  │ 47 queue items    │
│ Recent Activity  │ ✅ Pass  │ Active 2h ago     │
└──────────────────┴──────────┴───────────────────┘

⚠️ Warnings (1):
  • configs/areas.yaml missing

📈 Summary: 5 passed, 1 warning, 0 failed

Actions:
  ❯ View detailed report
    Fix warnings
    Run full diagnostics
    Export health report
    Done

4. Configuration Wizard (origin-workflow config)

Current Manual Process:

vim configs/schedule.yaml
vim configs/priorities.yaml
vim configs/areas.yaml

New Interactive Experience:

$ origin-workflow config

? What would you like to configure?
  ❯ Work schedule & energy blocks
    Priority weights
    Life areas & tags
    LLM integration
    Advanced settings

Selected: Work schedule & energy blocks

Current Schedule:
  Work hours: 9:00 AM - 5:00 PM
  High energy: 9:00 AM - 12:00 PM
  Medium energy: 1:00 PM - 4:00 PM
  Low energy: 4:00 PM - 5:00 PM

? Update work start time? (9:00 AM)
? Update work end time? (5:00 PM)

? Your peak productivity happens:
  ❯ Morning (9 AM - 12 PM)
    Afternoon (1 PM - 4 PM)
    Evening (6 PM - 9 PM)
    I'm consistent all day

✓ Schedule updated!

? Configure break intervals?
  Short breaks: 15 minutes
  Long breaks: 30 minutes

✓ Configuration saved to configs/schedule.yaml

What's next?
  ❯ Configure another setting
    Preview schedule
    Test with sample plan
    Done

5. Process Workflow (origin-workflow process)

Current Manual Process:

node automation/normalize.js
node automation/issue_generator.js
node automation/llm_summarizer_stub.js --mode stub

New Interactive Experience:

$ origin-workflow process

? What would you like to process?
  ❯ Normalize reading queue
    Generate issues
    Run LLM summaries
    Full pipeline
    Custom workflow

Selected: Full pipeline

⏳ Step 1/3: Normalizing reading queue...
  📱 Processing Twitter bookmarks... 23 items
  📚 Processing journal papers... 15 items
  📥 Processing inbox items... 9 items
  🔗 Deduplicating... removed 3 duplicates
✓ Reading queue normalized (44 items)

⏳ Step 2/3: Generating issues...
  📝 Creating issue files... 44 issues
✓ Issues generated

⏳ Step 3/3: Running LLM summaries...
  ⚠️  LLM integration not configured

? Would you like to:
  ❯ Skip LLM summaries (continue)
    Configure LLM integration now
    Run in stub mode (testing)
    Cancel

Selected: Run in stub mode

  🤖 Generating stub summaries... 5 items
✓ Stub summaries generated

✨ Pipeline complete!

📊 Summary:
  • 44 items processed
  • 44 issues created
  • 5 summaries generated
  • 3 duplicates removed

? View processing report? (Y/n)

State Management

Context Awareness

The CLI maintains awareness of:

  • Last command executed
  • Current working context (daily plan, capture mode, etc.)
  • User preferences (saved to ~/.origin-workflow/config.json)
  • Recent activity and patterns

Intelligent Defaults

  • Suggests next logical action based on context
  • Remembers frequently used options
  • Learns from user patterns (with privacy)

Error Handling

Graceful Degradation

  1. Missing Dependencies: Offer to install or provide alternatives
  2. File System Issues: Suggest fixes and permissions
  3. Configuration Errors: Guide through correction with wizard
  4. Network Failures: Retry with exponential backoff

User-Friendly Messages

❌ Error: Could not find reading queue

💡 Suggestions:
  1. Run: origin-workflow process --normalize
  2. Check if data/reading-queue.json exists
  3. Run: origin-workflow health

? Would you like me to:
  ❯ Create empty reading queue
    Run normalization now
    Show detailed error
    Exit

Performance Targets

  • Startup time: < 500ms
  • Command execution: < 2s for common operations
  • Interactive prompts: < 100ms response time
  • Progress updates: Real-time (60fps)
  • Memory footprint: < 50MB for typical operations

Testing Strategy

  1. Unit Tests: Individual command logic
  2. Integration Tests: Full workflow execution
  3. UI Tests: Interactive prompt flows
  4. Performance Tests: Response time benchmarks
  5. User Acceptance Tests: Real workflow scenarios

Installation & Distribution

Global Installation

npm install -g origin-workflow-cli

# Or via repository
cd origin-workflow
npm link

First-Run Experience

$ origin-workflow

Welcome to Origin Workflow! 🚀

It looks like this is your first time running the CLI.
Let's get you set up in less than 5 minutes.

? Where is your Origin Workflow directory?
  ❯ Current directory
    Choose another location
    Clone from remote

? Configure work schedule now? (Y/n)

⏳ Setting up...

✓ Configuration complete!

Ready to go! Try:
  origin-workflow daily     # Start your day
  origin-workflow capture   # Capture ideas
  origin-workflow health    # Check system

Need help? Run: origin-workflow --help

Success Metrics

  • Setup Time: < 5 minutes for new users
  • Daily Overhead: < 3 minutes for routine operations
  • Command Reduction: 15+ commands → 1 CLI
  • Error Reduction: 90% fewer user errors
  • User Satisfaction: 4.5+ stars from early users

Migration Plan

Phase 1: Core Commands (Week 1)

  • Daily workflow
  • Capture workflow
  • Health dashboard

Phase 2: Advanced Features (Week 2)

  • Configuration wizard
  • Process workflows
  • LLM integration

Phase 3: Polish & Testing (Week 3)

  • Error handling improvements
  • Performance optimization
  • Documentation
  • User testing

Phase 4: Release (Week 4)

  • Package for distribution
  • Create video tutorials
  • Launch announcement