🌟 Behflow

An AI-powered, self-hosted task management system that brings intelligence to your workflow

Behflow is a modern, AI-driven to-do manager designed for simplicity, efficiency, and seamless integration. Named after "Behnaz" (My partner), this project is a heartfelt tribute to the inspiration behind its creation. Behflow empowers users to manage their tasks intelligently while leveraging cutting-edge AI technology to automate processes and enhance productivity.

✨ Features

🤖 AI-Powered Intelligence

• LangGraph-based Agent System: Conversational AI agent for intelligent task orchestration
• Automated Process Scheduling: Time-based triggers with cron-like scheduling
• Smart Task Rescheduling: Automatically reschedule tasks based on context and priorities
• Interactive Chat Assistant: Markdown-supported chat interface for natural task interaction

📋 Task Management

• Multi-Status Tracking: Organize tasks by status (Not Started, In Progress, Completed, Blocked)
• Priority Management: Set and manage task priorities with intelligent suggestions
• Timezone-Aware Scheduling: Support for both Gregorian and Jalali date systems
• Manual & Automatic Triggers: Execute processes on demand or via scheduled automation

🔐 Authentication & Security

• User Authentication: Secure login and registration system
• Session Management: Robust session handling and user state management
• Self-Hosted Privacy: Complete control over your data and deployment

🎨 Modern Interface

• Responsive Design: Optimized for desktop and mobile devices
• Theme Switching: Toggle between Atom One Dark Pro and light themes
• Real-time Updates: Live task status updates and notifications
• Intuitive Navigation: Clean, user-friendly interface design

🛠 Developer-Friendly

• Docker-Ready: Full containerization with Docker Compose
• API-First Architecture: RESTful APIs built with FastAPI
• Modular Structure: Clean separation of concerns and maintainable codebase
• Extensive Documentation: Comprehensive guides and architecture documentation

🏗 Project Architecture

Behflow/
├── 📚 docs/                    # Comprehensive documentation
│   ├── architecture.md         # System architecture overview
│   ├── automated_processes.md  # Automation system guide
│   └── TASKS.md                # Development tasks & roadmap
├── 🔧 infra/                   # Infrastructure & deployment
│   ├── docker-compose.yml      # Multi-container orchestration
│   └── migrations/             # Database schema migrations
├── 💻 src/
│   ├── 🖥 backend/             # FastAPI REST API server
│   │   ├── app/
│   │   │   ├── api/            # API routes (auth, chat, tasks)
│   │   │   ├── database/       # Database models & services
│   │   │   ├── main.py         # FastAPI application entry point
│   │   │   └── scheduler.py    # Background task scheduler
│   │   └── requirements.txt    # Python dependencies
│   ├── 🌐 frontend/            # Modern web interface
│   │   ├── index.html          # Main application page
│   │   ├── login.html          # Authentication pages
│   │   ├── app.js              # Task management & chat logic
│   │   └── styles.css          # Atom One Dark Pro theme
│   ├── 🤖 behflow_agent/       # AI Agent system (LangGraph)
│   │   ├── agent.py            # Main agent orchestrator
│   │   ├── nodes/              # Processing nodes
│   │   ├── models/             # Data models (Task, Process)
│   │   └── tools.py            # Agent tools & utilities
│   └── 🔄 shared/              # Shared utilities
└── 📜 LICENSE                  # MIT License

🚀 Quick Start

📋 Prerequisites

• 🐳 Docker & Docker Compose
• 🐍 Python 3.9+ (for local development)
• 📦 Node.js (for frontend development)

⚡ Installation

🐳 Docker Setup (Recommended)

# Clone the repository
git clone https://github.com/artaasd95/behflow.git
cd behflow

# Launch all services with Docker Compose
cd infra
docker compose up --build -d

# Access the application
# 🌐 Frontend: http://localhost:3000
# 🔌 Backend API: http://localhost:8010
# 🗄️ Database: localhost:15432 (postgres)

# Database is automatically initialized on first startup!
# All tables, indexes, and default data are created automatically.

First Time Setup: The database will automatically initialize with all required tables and configurations. No manual setup needed!

🛠 Local Development Setup

# Backend setup
cd src/backend
pip install -r requirements.txt
python -m app.main

# Frontend setup (in new terminal)
cd src/frontend
# Serve with your preferred static server
python -m http.server 8080

# Agent service (in new terminal)
cd src/behflow_agent
pip install -r requirements.txt

🎯 First Steps

1. Register your account at http://localhost:8080/register.html
2. Login and start creating your first tasks
3. Chat with the AI assistant to manage tasks naturally
4. Explore automated processes in the documentation

📚 Documentation

Explore comprehensive documentation in the docs folder:

Document	Description
🏗 Architecture	System design, components, and request flow
📡 API Documentation	REST API endpoints, requests, and responses
🤖 Agent System	AI agent architecture and tools
🗄 Database Schema	Database models, services, and migrations
🛠 Database Setup	Database initialization, migrations, and troubleshooting
🌐 Frontend Guide	UI components and client-side logic
🔗 Integration Guide	Third-party integrations and webhooks
🚀 Deployment Guide	Production deployment strategies
⚙️ Configuration	Environment variables and settings
🧪 Testing Guide	Testing strategies and best practices
⚙️ Automated Processes	Scheduling, triggers, and automation system
📋 Tasks & Changes	Development roadmap and change log

🤝 Contributing

We welcome contributions! Here's how you can help:

• 🐛 Report bugs by opening an issue
• 💡 Suggest features through discussions
• 🔧 Submit pull requests for improvements
• 📝 Improve documentation and examples

Please read our contribution guidelines and follow the existing code style.

🛠 Tech Stack

• Backend: FastAPI, SQLAlchemy, PostgreSQL
• Frontend: Vanilla JavaScript, HTML5, CSS3
• AI Engine: LangGraph, OpenAI/Anthropic integration
• Infrastructure: Docker, Docker Compose, Nginx
• Database: PostgreSQL with timezone awareness
• Testing: pytest, Jest, Testing Library

🧪 Testing

Behflow includes comprehensive test coverage for backend, frontend, and agent components.

Running Tests

# Backend tests
cd src/backend
pytest

# With coverage
pytest --cov=app --cov-report=html

# Specific test file
pytest tests/backend/test_auth_service.py

# Agent tests
pytest tests/agent/

# Frontend tests (requires Jest setup)
cd src/frontend
npm test

Test Structure

tests/
├── conftest.py              # Shared fixtures
├── backend/
│   ├── test_auth_service.py
│   ├── test_task_service.py
│   └── test_api_endpoints.py
├── agent/
│   ├── test_tools.py
│   └── test_builder.py
└── frontend/
    └── README.md             # Frontend test guide

Test Coverage

Our testing strategy follows the test pyramid:

• Unit Tests (70%): Fast, isolated tests for individual functions
• Integration Tests (20%): Test component interactions
• End-to-End Tests (10%): Complete workflow validation

For detailed testing guidelines, see Testing Documentation.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💖 Acknowledgments

Named with love after "Behnaz" - the inspiration behind this project.

---

🌟 Behflow: Where AI meets productivity

Simplifying task management with intelligent automation