{"id":25002110,"url":"https://github.com/tomatyss/pythmata","last_synced_at":"2026-02-28T05:03:50.843Z","repository":{"id":275380644,"uuid":"925408343","full_name":"tomatyss/pythmata","owner":"tomatyss","description":"Python-based BPMN workflow engine","archived":false,"fork":false,"pushed_at":"2025-04-13T18:32:06.000Z","size":3564,"stargazers_count":2,"open_issues_count":9,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T19:41:14.423Z","etag":null,"topics":["automation","bpmn","processes","workflow"],"latest_commit_sha":null,"homepage":"https://tomatyss.github.io/pythmata/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomatyss.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"tomatyss","thanks_dev":null,"custom":null}},"created_at":"2025-01-31T20:27:59.000Z","updated_at":"2025-04-13T18:32:02.000Z","dependencies_parsed_at":"2025-02-02T05:21:11.268Z","dependency_job_id":"8e71ae0f-ac66-43f3-9159-2f545b7da68e","html_url":"https://github.com/tomatyss/pythmata","commit_stats":null,"previous_names":["tomatyss/pythmata"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomatyss%2Fpythmata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomatyss%2Fpythmata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomatyss%2Fpythmata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomatyss%2Fpythmata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomatyss","download_url":"https://codeload.github.com/tomatyss/pythmata/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250349716,"owners_count":21416005,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","bpmn","processes","workflow"],"created_at":"2025-02-04T21:36:11.693Z","updated_at":"2026-02-28T05:03:45.809Z","avatar_url":"https://github.com/tomatyss.png","language":"Python","readme":"# Pythmata\n\nA Python-based BPMN workflow engine with a modern React frontend.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.115.8-009688.svg)](https://fastapi.tiangolo.com)\n[![React](https://img.shields.io/badge/react-19.0.0-61DAFB.svg)](https://reactjs.org/)\n[![Version](https://img.shields.io/badge/version-0.1.0-brightgreen.svg)](https://github.com/yourusername/pythmata)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-14+-336791.svg)](https://www.postgresql.org/)\n[![Documentation](https://img.shields.io/badge/docs-MkDocs-blue.svg)](https://www.mkdocs.org/)\n\n\n\u003e **⚠️ DISCLAIMER: Work in Progress**  \n\u003e This project is under active development and has not reached a stable release yet.  \n\u003e APIs, features, and functionality may change without notice.  \n\u003e Not recommended for production use at this time.\n\n## Overview\n\nPythmata is a workflow engine that implements the Business Process Model and Notation (BPMN) standard. It allows users to design, deploy, and execute business processes using a visual BPMN modeler, while providing powerful scripting capabilities for task automation.\n\n## Architecture\n\n### Frontend (React/TypeScript)\n\nThe frontend is built with modern React and TypeScript, following a component-based architecture with:\n\n- **State Management**:\n  - Zustand for global state management\n  - React Query for server state and data fetching\n  - React Hook Form for form handling and validation\n\n- **UI Components**:\n  - Material-UI (MUI) as the component library\n  - Custom shared components for consistency\n  - BPMN.js for process modeling and visualization\n\n- **Key Features**:\n  - Real-time process monitoring\n  - Visual BPMN process designer\n  - BPMN diagram import and export\n  - Script editor for task automation\n  - Gateway condition configuration\n  - Process instance management\n  - Variable inspection and modification\n  - WebSocket-based chat system with LLM integration\n    - Real-time streaming of LLM responses\n    - Multi-client chat sessions\n    - Typing indicators\n\n### Backend (Python)\n\nThe backend is built with Python, implementing a robust BPMN execution engine with:\n\n- **Core Engine**:\n  - BPMN element implementations\n  - Process instance management\n  - Event handling and propagation\n  - Script execution environment\n\n- **Services**:\n  - Process definition management\n  - Instance execution and control\n  - Variable management\n  - Script execution and sandboxing\n  - WebSocket-based chat system\n    - LLM integration with streaming responses\n    - Multi-client session management\n    - Real-time messaging and notifications\n\n### Infrastructure\n\nThe project uses a modern containerized architecture with:\n\n- **Docker Containers**:\n  - Frontend (Node.js/Nginx)\n  - Backend (Python)\n  - PostgreSQL (Process data)\n  - Redis (Caching/Pub-Sub)\n  - RabbitMQ (Message Queue)\n\n- **Development Tools**:\n  - Docker Compose for local development\n  - TypeScript for type safety\n  - ESLint/Prettier for code formatting\n  - Vite for frontend development\n\n## Key Concepts\n\n### Process Definitions\n\n- **BPMN Modeling**: Users can create and modify process definitions using the visual BPMN modeler\n- **Version Control**: Process definitions are versioned for tracking changes\n- **XML Storage**: Processes are stored in BPMN 2.0 XML format\n\n### Process Instances\n\n- **Execution**: Running instances of process definitions\n- **State Management**: Tracks current state and history\n- **Variable Handling**: Manages process variables and their scopes\n- **Event System**: Handles BPMN events and message flows\n\n### Script Tasks\n\n- **Python Scripting**: Embedded Python script execution\n- **Sandboxing**: Secure script execution environment\n- **Variable Access**: Scripts can access and modify process variables\n- **External Integration**: Ability to interact with external systems\n\n### Plugin System\n\n- **Custom Service Tasks**: Extend the engine with custom service tasks\n- **Plugin Discovery**: Automatic discovery and loading of plugins\n- **Dependency Management**: Plugin-specific dependency management\n- **Isolation**: Keep custom code separate from the core engine\n\n### Event System\n\n- **BPMN Events**: Implementation of start, intermediate, and end events\n- **Message Events**: Handling of message-based communication\n- **Timer Events**: Scheduling and execution of time-based events\n- **Error Handling**: Error events and exception management\n\n## Technical Implementation\n\n### Frontend Architecture\n\n1. **Component Structure**:\n   - Shared components for reusability\n   - Page-based routing\n   - Layout management\n   - Modal and dialog system\n\n2. **State Management**:\n   - Process store\n   - Instance store\n   - UI state management\n   - Form state handling\n\n3. **API Integration**:\n   - Axios for HTTP requests\n   - WebSocket for real-time updates\n   - Error handling and retries\n   - Request/response interceptors\n\n4. **Styling and Theming**:\n   - Material-UI theming\n   - Tailwind CSS utilities\n   - Responsive design\n   - Dark/light mode support\n\n### Backend Architecture\n\n1. **Core Engine**:\n   - BPMN element implementations\n   - Process execution logic\n   - Event handling system\n   - Variable management\n\n2. **Data Layer**:\n   - PostgreSQL for persistent storage\n   - Redis for caching and pub/sub\n   - RabbitMQ for async tasks\n\n3. **API Layer**:\n   - RESTful API endpoints\n   - WebSocket connections\n   - Authentication/Authorization\n   - Request validation\n\n4. **Script Execution**:\n   - Python script parsing\n   - Sandboxed execution\n   - Variable context management\n   - Error handling\n\n## Development Setup\n\n1. **Prerequisites**:\n   - Docker and Docker Compose\n   - Node.js (for local frontend development)\n   - Python (for local backend development)\n\n2. **Environment Setup**:\n   ```bash\n   # Clone repository\n   git clone https://github.com/yourusername/pythmata.git\n   cd pythmata\n\n   # Start services\n   docker-compose up\n   ```\n\n3. **Development Workflow**:\n   - Frontend development server: http://localhost:3000\n   - Backend API: http://localhost:8000\n   - PostgreSQL: localhost:5432\n   - Redis: localhost:6379\n   - RabbitMQ: localhost:5672 (Management: 15672)\n\n## Test Setup\n\n1. **Test Database**:\n   - The test suite uses a separate database (`pythmata_test` by default)\n   - Database is automatically created and migrated before tests run\n   - Tables are created fresh for each test and cleaned up afterward\n\n2. **Environment Variables**:\n   ```bash\n   # Database Configuration\n   POSTGRES_USER=pythmata          # Database user\n   POSTGRES_PASSWORD=pythmata      # Database password\n   POSTGRES_HOST=localhost         # Database host\n   POSTGRES_PORT=5432             # Database port\n   POSTGRES_TEST_DB=pythmata_test # Test database name\n   DB_POOL_SIZE=5                # Database connection pool size\n   DB_MAX_OVERFLOW=10            # Maximum pool overflow\n\n   # Redis Configuration\n   REDIS_HOST=localhost\n   REDIS_PORT=6379\n   REDIS_POOL_SIZE=10\n\n   # RabbitMQ Configuration\n   RABBITMQ_USER=guest\n   RABBITMQ_PASSWORD=guest\n   RABBITMQ_HOST=localhost\n   RABBITMQ_PORT=5672\n   RABBITMQ_CONNECTION_ATTEMPTS=3\n   RABBITMQ_RETRY_DELAY=1\n   ```\n\n3. **Running Tests**:\n   ```bash\n   # Navigate to backend directory\n   cd backend\n\n   # Run all tests\n   pytest\n\n   # Run specific test file\n   pytest tests/path/to/test_file.py\n\n   # Run with coverage report\n   pytest --cov=src\n   ```\n\n4. **CI/CD Integration**:\n   - Test database is automatically created if it doesn't exist\n   - Migrations are applied before test execution\n   - Environment variables can be configured in CI/CD pipeline\n   - Test results and coverage reports are generated\n\n## Project Structure\n\n```\npythmata/\n├── frontend/                # React frontend application\n│   ├── src/\n│   │   ├── components/     # Shared React components\n│   │   ├── hooks/         # Custom React hooks\n│   │   ├── lib/           # Utility functions and services\n│   │   ├── pages/         # Page components\n│   │   ├── store/         # State management\n│   │   └── types/         # TypeScript type definitions\n│   └── public/            # Static assets\n├── backend/               # Python backend application\n│   ├── src/\n│   │   ├── core/         # Core engine implementation\n│   │   ├── api/          # API endpoints\n│   │   ├── models/       # Data models\n│   │   └── services/     # Business logic services\n│   └── tests/            # Backend tests\n└── config/               # Configuration files\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n\u003ca href=\"https://www.buymeacoffee.com/tomatyss\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" \u003e\u003c/a\u003e\n","funding_links":["https://buymeacoffee.com/tomatyss","https://www.buymeacoffee.com/tomatyss"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomatyss%2Fpythmata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomatyss%2Fpythmata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomatyss%2Fpythmata/lists"}