CONTRIBUTING.md

Contributing to SmythOS UI

Welcome! We're excited that you want to contribute to SmythOS UI, the comprehensive platform for building and deploying AI agents.

Contents

• Contributing to SmythOS UI
  • Contents
  • Code of Conduct
  • Repository Structure
  • Development Setup
    • Prerequisites
      • Node.js
      • pnpm
        • pnpm workspaces
      • corepack
    • Setting Up SmythOS UI
    • Starting the Application
  • Development Workflow
    • Basic Development Process
    • Package-Specific Development
      • Targeted Development
    • Performance Considerations
    • Community Contribution Guidelines
      • 1. Response Timeline
      • 2. Code Quality Standards
      • 3. Pull Request Requirements
      • 4. Review Process for Non-Compliant PRs
  • Contributor License Agreement

Code of Conduct

This project and all participants are governed by our Code of Conduct. By participating, you agree to uphold professional standards and create a welcoming environment for all contributors. Please report any unacceptable behavior to the maintainers.

Repository Structure

SmythOS UI is organized as a monorepo with multiple packages, each serving specific functions:

The key directories and packages:

• /packages - All SmythOS UI modules
• /packages/app - Main application containing the Agent builder workspace, React frontend, and backend services
• /packages/app/src/builder-ui - Workflow builder interface for building agents
• /packages/app/src/react - React-based user interface components and features
• /packages/app/src/backend - UI Backend API services and routes
• /packages/middleware - Core api for facilitating database / low-level operations
• /packages/runtime - Runtime server for agent execution and debugging

Development Setup

To contribute to SmythOS UI, you'll need to set up the development environment with all required dependencies and proper package linking.

Prerequisites

Node.js

Node.js version 20.x or newer is required for development.

pnpm

pnpm version 10.2 or newer is required for package management. We strongly recommend installing it with corepack.

pnpm workspaces

SmythOS UI uses pnpm workspaces to manage the monorepo structure. This automatically creates file-links between interdependent packages and ensures consistent dependency management across all modules.

corepack

Enable Node.js corepack with corepack enable.

Install the correct pnpm version using corepack prepare pnpm@10.12.2 --activate.

macOS (Homebrew): brew install corepack (Node via Homebrew excludes it)

Windows: Run as admin → corepack enable && corepack prepare --activate

Setting Up SmythOS UI

IMPORTANT: Execute all steps below at least once to establish the development environment!

1. Fork the SmythOS UI repository.

2. Clone your forked repository:

   git clone https://github.com/<your_github_username>/smythos-studio.git

3. Navigate to the repository:

   cd smythos-studio

4. Add the original repository as upstream:

   git remote add upstream https://github.com/SmythOS/smythos-studio.git

5. Set up MySQL Database (Required):

   SmythOS UI requires a MySQL database. Choose one of the options below:

   Option 1: Quick Docker Setup (Recommended)

   docker run --name smythos-mysql-local \
     -e MYSQL_ROOT_PASSWORD=smythos_root_pass \
     -e MYSQL_DATABASE=smythos_db \
     -p 3306:3306 \
     -d mysql

   Option 2: Use your existing MySQL instance

   Ensure you have MySQL 8.0+ running and create a database for SmythOS UI.

6. Configure Environment Variables:

   cp .env.example .env

   ⚠️ IMPORTANT: If you have your own MySQL instance, open the .env file and update the DB connection keys:

   DATABASE_HOST=localhost
   DATABASE_USER=root
   DATABASE_PASSWORD=smythos_root_pass
   DATABASE_NAME=smythos_db

   💡 Note: These keys are essential for database migrations and application startup. Make sure it matches your MySQL setup exactly.

7. Install all dependencies and link packages:

   pnpm install

8. Build all packages:

   pnpm build

Starting the Application

To start SmythOS UI in development mode:

pnpm dev

To start in production mode:

pnpm start

Once the application has started, you can access it at:

http://localhost:5050

Development Workflow

Basic Development Process

1. Start SmythOS UI in development mode:

   pnpm dev

2. Make your changes
3. Verify functionality in production mode:

   pnpm build
   pnpm start

4. Write and run tests
5. Commit your changes and create a pull request

Targeted Development

For highly focused development, run specific packages individually:

Example 1: Working on React components

# Terminal 1: Start Middleware
cd packages/middleware
pnpm dev

# Terminal 2: Run Runtime
cd packages/runtime
pnpm dev

# Terminal 3: Run UI server
cd packages/app
pnpm dev

Example 2: Middleware development

# Terminal 1: Watch middleware package (migrations run automatically)
cd packages/middleware
pnpm dev

# Terminal 2: Run dependent services
cd packages/app
pnpm dev

Example 3: Runtime development

# Terminal 1: Run runtime package
cd packages/runtime
pnpm dev

Performance Considerations

Full development mode (pnpm dev) runs multiple concurrent processes:

1. TypeScript compilation for each package
2. Nodemon restarting backend services
3. Vite dev server for React with Hot Module Replacement
4. Multiple build processes for various packages

Resource impact:

• High CPU and memory consumption
• File system watching overhead, particularly on:
  • Network-attached storage
  • Virtual machines with shared folders
  • Systems with slow I/O performance
• Resource usage scales with active packages

Optimization recommendations:

1. Use targeted development commands based on your work
2. Close unnecessary applications to free resources
3. Monitor system performance and adjust workflow accordingly

---

Community Contribution Guidelines

1. Response Timeline

Contributors should address feedback or requested changes within 14 days. Pull requests without response or updates will be automatically closed but can be reopened once changes are applied.

2. Code Quality Standards

• Follow Style Guidelines:
  • Adhere to SmythOS UI coding standards and formatting conventions
  • Use provided linting tools and configurations
• TypeScript Compliance:
  • Ensure full TypeScript compatibility
• Code Reusability:
  • Reuse existing components, utilities, and patterns
  • Avoid duplicating functionality across packages
  • Maintain consistency in parameter and component definitions

3. Pull Request Requirements

• Focused Scope:
  • Limit PRs to single features or fixes
• Clear Naming:
  • Follow descriptive PR title conventions
• New Features:
  • Major new features should be discussed with maintainers before implementation
  • Ensure alignment with SmythOS UI roadmap and architecture
• Documentation:
  • Update relevant documentation for new features
  • Include inline code comments for complex logic

4. Review Process for Non-Compliant PRs

• Large/Unfocused PRs: Will be returned for segmentation into smaller, focused changes
• Architectural Concerns: PRs that don't align with project architecture will require discussion and potential redesign

Contributor License Agreement

To ensure clear intellectual property rights and enable smooth collaboration, contributors must sign our Contributor License Agreement. This process is automated - when you submit your first pull request, a bot will provide instructions for signing the agreement.

The agreement uses plain English and is designed to protect both contributors and the project while enabling open-source collaboration.

---

Thank you for contributing to SmythOS UI! Your contributions help make AI agent development more accessible and powerful for everyone.