Contributing to Flexus

Thank you for your interest in contributing to Flexus! This guide will help you get started with the codebase and make your first contribution.

Project Structure

Flexus is split across multiple repositories:

Your First Contribution

New to Flexus? Follow this step-by-step guide:

1. Fork the Repository

   Go to the repository on GitHub and click the “Fork” button in the top right.

2. Clone Your Fork

   git clone https://github.com/YOUR_USERNAME/flexus.git
   cd flexus

3. Add Upstream Remote

   git remote add upstream https://github.com/smallcloudai/flexus.git

4. Create a Branch

   git checkout -b feature/my-awesome-feature

5. Make Your Changes

   Follow the code style guidelines below. Keep changes focused and atomic.

6. Run Tests

   python -m pytest          # Backend tests
   npm run test              # Frontend tests (in flexus_frontend/)

7. Commit Your Changes

   git add .
   git commit -m "feat: add awesome feature"

8. Push and Create PR

   git push origin feature/my-awesome-feature

   Then go to GitHub and create a Pull Request.

Development Setup

Prerequisites

• Python 3.10+ — For backend and bots
• Node.js 18+ — For frontend
• Docker & Docker Compose — For local services (Postgres, Redis)
• Git — For version control

Quick Commands

We recommend creating a Makefile or shell aliases for common operations:

# Suggested workflow commands

# Setup everything
make setup
# Equivalent to:
# docker-compose -f docker-compose.dev.yml up -d
# pip install -e ".[dev]"
# python -m prisma migrate deploy

# Run backend
make dev
# Equivalent to: python -m flexus_backend.flexus_v1_server

# Run frontend
make frontend
# Equivalent to: cd flexus_frontend && npm run dev

# Run all tests
make test
# Equivalent to: python -m pytest && cd flexus_frontend && npm run test

# Lint code
make lint
# Equivalent to: ruff check . && mypy . && cd flexus_frontend && npm run lint

Clone Repositories

# Create workspace
mkdir flexus-dev && cd flexus-dev

# Clone repositories
git clone https://github.com/smallcloudai/flexus.git
git clone https://github.com/smallcloudai/flexus-client-kit.git

Backend Setup

cd flexus

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install dependencies
pip install -e ".[dev]"

# Start local services (Postgres, Redis)
docker-compose -f docker-compose.dev.yml up -d

# Run migrations
python -m prisma migrate deploy

# Start backend
python -m flexus_backend.flexus_v1_server

Frontend Setup

cd flexus/flexus_frontend

# Install dependencies
npm install

# Start dev server
npm run dev

Client Kit Setup

cd flexus-client-kit

# Install in dev mode
pip install -e ".[dev]"

# Set environment
export FLEXUS_API_BASEURL=http://localhost:8000/
export FLEXUS_API_KEY=your-dev-api-key

Environment Variables

Backend (flexus)

Client Kit (bots)

Copy .env.example to .env and fill in your values.

Pre-commit Hooks

We use pre-commit hooks to ensure code quality before commits.

Setup

# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

# Run manually on all files
pre-commit run --all-files

What Gets Checked

Code Style

Python

We don’t follow PEP8 strictly. Key rules:

# Trailing commas and indent independent of brackets
def my_func(
    x: int,
    y: int,
) -> int:
    return x + y

my_func(
    5,
    6,
)

Naming:

• Use prefixed names for data fields: fgroup_name, ktask_id, ft_title
• Local variables can be short: x, i, args
• No generic names like data, result, item for important things

Imports:

• Prefer import xxx over from xxx import f
• Exception: very standard imports like from typing import Any
• Never import inside functions

Comments:

• No docstrings unless explaining something clever
• Comment tricks, hacks, and non-obvious decisions
• Mark future improvements with XXX

Error Handling:

• Never except Exception without exc_info=e logging
• Catch specific exceptions only
• External API errors use logger.info, not logger.error

TypeScript (Frontend)

Naming:

• snake_case for backend fields: ws_id, fgroup_id
• camelCase for TypeScript variables
• kebab-case for URLs and files

Error Handling:

• Never use ?. to silently ignore errors
• Always log to console AND show error bubble
• No “best behavior” — fail visibly

// Bad
if (result.data?.field) { ... }

// Good
if (!result.data || !result.data.field) {
    console.error('COMPONENT_NAME FAILS:', result);
    errorBubble.setError(result.error);
    return;
}

GraphQL:

const { execute: meaningfulNameExecute } = useMutation(`
    mutation WhoCallsAndWhy($input: FType!) {
        real_name(input: $input) { output_field }
    }
`);

Making Changes

Branch Naming

feature/short-description
fix/issue-number-description
docs/what-you-documented

Commit Messages

We use Conventional Commits:

type(scope): short description

Longer explanation if needed.

Fixes #123

Types:

• feat — New feature
• fix — Bug fix
• docs — Documentation only
• refactor — Code change that neither fixes a bug nor adds a feature
• test — Adding or updating tests
• chore — Maintenance tasks

Testing

# Python tests
python -m pytest

# Frontend tests
npm run test

# Bot syntax check
python -m py_compile my_bot.py my_prompts.py my_install.py

Pull Requests

1. Fork the repository
2. Create branch from main
3. Make changes following style guide
4. Test your changes
5. Submit PR with clear description

PRs are automatically checked for:

• Tests passing
• Linting passing
• No secrets committed

Troubleshooting

Docker Issues

Ports already in use:

# Check what's using port 5432 (Postgres)
lsof -i :5432
# Kill the process or use different port in docker-compose.yml

Containers won’t start:

# Check logs
docker-compose -f docker-compose.dev.yml logs

# Reset and rebuild
docker-compose -f docker-compose.dev.yml down -v
docker-compose -f docker-compose.dev.yml up -d --build

Database Issues

Prisma migrate fails:

# Reset database (WARNING: deletes all data)
python -m prisma migrate reset

# Generate Prisma client
python -m prisma generate

pgvector extension missing:

-- Connect to Postgres and run:
CREATE EXTENSION IF NOT EXISTS vector;

Frontend Issues

npm install fails:

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

Wrong Node version:

# Check version (need 18+)
node --version

# Use nvm to switch
nvm install 18
nvm use 18

Bot Issues

Bot won’t connect:

• Check FLEXUS_API_BASEURL is correct (include trailing slash)
• Verify API key is valid
• Ensure backend is running

LLM rate limits:

• Check your API key quota
• Set LITELLM_MODEL to a less restricted model
• Add retry logic with backoff

Common Errors

Areas to Contribute

Good First Issues

Look for issues labeled good first issue:

• Documentation improvements
• Bug fixes with clear reproduction
• Small feature additions

Bot Development

Create new bots for the marketplace:

• Follow patterns in flexus_simple_bots/
• Use frog/ as a reference
• Include tests and documentation

Integrations

Add new integrations to client kit:

• New messenger platforms
• External services
• API connectors

Frontend Improvements

• UI/UX enhancements
• Accessibility improvements
• Mobile optimization

Documentation

• Fix typos and errors
• Add examples
• Improve explanations
• Translate to other languages

Component Documentation

Each component has specific patterns and guidelines:

Release Process

Versioning

We follow Semantic Versioning:

• MAJOR (1.0.0 -> 2.0.0): Breaking changes
• MINOR (1.0.0 -> 1.1.0): New features, backward compatible
• PATCH (1.0.0 -> 1.0.1): Bug fixes, backward compatible

Release Steps

1. Create release branch: release/v1.2.0
2. Update CHANGELOG.md: Document all changes
3. Bump version: In pyproject.toml, package.json
4. Create PR: Merge to main
5. Tag release: git tag v1.2.0
6. GitHub Release: Create with release notes
7. Publish artifacts:
   • Docker images to registry
   • Python packages to PyPI (client-kit)

Changelog Format

## [1.2.0] - 2024-01-15

### Added
- New feature X (#123)

### Changed
- Updated behavior of Y (#124)

### Fixed
- Bug in Z (#125)

### Deprecated
- Old API endpoint (use new one)

Security

Reporting Vulnerabilities

Email security@flexus.team for security issues. Do not open public issues.

Security Guidelines

• Never commit secrets or credentials
• Validate all user input
• Check permissions in handlers
• Use parameterized queries

Getting Help

• GitHub Discussions — Questions and ideas
• Discord — Real-time chat
• Issues — Bug reports and feature requests

Use issue templates when creating issues — they help us understand and address your needs faster.

Code of Conduct

We follow the Contributor Covenant. Be respectful, inclusive, and constructive.

License

Flexus is MIT licensed. Your contributions will be under the same license.