Contributing to MovaLab

Whether you're fixing bugs, adding features, or improving documentation - every contribution helps build better agency tools.

AI Tools Can Accelerate Your Workflow

Tools like Cursor, Claude, and GitHub Copilot can help speed up development. Our codebase is well-documented and TypeScript-first, making it easier to navigate and contribute.

We're a welcoming community - don't hesitate to ask questions in Discord or open a draft PR for feedback.

Ways to Contribute

Start with what feels comfortable. Every contribution matters.

Share Your Workflows

Tell us how your agency works - your processes become features

Request Features

What tool do you wish existed? Open a GitHub issue

Join Discussions

Help answer questions, share experiences in Discord

Test & Report Bugs

Try features, report issues - this is hugely valuable

Improve Docs

Fix typos, clarify instructions, add examples

Contribute Code

From small fixes to new features - all skill levels welcome

Development Setup

Zero-configuration setup - everything runs locally with Docker. No cloud accounts required.

1. Fork & Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/movalab.git
cd movalab

2. Run Setup Script

# macOS / Linux / Git Bash:
./scripts/first-time-setup.sh

# Windows CMD / PowerShell:
scripts\first-time-setup.bat

The script automatically installs dependencies, starts Docker services, applies migrations, and creates test data.

3. Start Development Server

npm run dev

Open http://localhost:3000 and login with superadmin@test.local / Test1234!

Docker Commands

npm run docker:start         # Start Supabase services
npm run docker:stop          # Stop services (preserves data)
npm run docker:reset         # Reset DB, re-run migrations
npm run docker:seed          # Reset DB + create seed users
npm run docker:health        # Verify setup
npm run docker:studio        # Open Supabase Studio

Database Structure

The database schema is defined in /supabase/migrations/. Key areas include:

Area	Tables	Description
Users & Auth	user_profiles, user_roles, roles	User management and RBAC
Accounts	accounts, account_members	Client account management
Projects	projects, project_assignments, tasks	Project and task tracking
Time Tracking	time_entries, clock_sessions	Capacity and time management
Workflows	workflow_templates, workflow_nodes	Visual workflow automation
Forms	form_templates, form_responses	Dynamic form builder

Important: RLS (Row Level Security) is mandatory on all tables. Don't disable it - this protects data isolation between users.

Code Style

TypeScript: All code should be written in TypeScript with proper types
Formatting: Follow existing code patterns in the codebase
Components: Use functional components with hooks
Naming: Use descriptive names for variables, functions, and components

Pull Request Process

Create a branch

git checkout -b feature/your-feature-name

Make your changes

with clear, focused commits

Test your changes

locally

Push to your fork

git push origin feature/your-feature-name

Open a Pull Request

against the main branch

PR Requirements

Provide a clear description of what changed and why
Ensure the build passes (npm run build)
Test your changes thoroughly
Keep PRs focused on a single change when possible

License

By contributing, you agree that your contributions will be licensed under the Sustainable Use License:

You Can

- Use for internal business purposes
- Self-host for your own business
- Modify for internal use
- Offer consulting/implementation services

You Cannot

- Host MovaLab as a paid service
- Resell or white-label MovaLab
- Embed in a commercial product

This is a "fair-code" license similar to n8n and other source-available projects. It protects against commercial exploitation while allowing agencies to use and benefit from the platform.

Questions?

Open a GitHub Discussion for general questions, or join our Discord community.

GitHub Discord