Contributing¶

We welcome contributions to Julee! This guide will help you get started.

Development Setup¶

Fork and clone the repository:

git clone https://github.com/yourusername/julee.git
cd julee

Create a virtual environment:

python -m venv .venv
source .venv/bin/activate

Install development dependencies:
```
pip install -e ".[dev,docs]"
```
Install pre-commit hooks:
```
pre-commit install
```

Code Style¶

We use the following tools to maintain code quality:

Ruff

Fast Python linter and formatter:

ruff check .
ruff format .

Mypy

Static type checking:

mypy api domain repositories services workflows

Pre-commit

Automated checks before commit:

pre-commit run --all-files

Testing¶

Running Tests¶

Run the test suite:

pytest

Run with coverage:

pytest --cov

Run specific test files:

pytest api/tests/test_app.py

Writing Tests¶

Place tests in tests/ directories adjacent to the code:

api/tests/ - API endpoint tests
domain/*/tests/ - Domain model and use case tests
repositories/*/tests/ - Repository implementation tests

Use pytest fixtures for common setup:

@pytest.fixture
def sample_document():
    return Document(
        id="test-doc",
        name="Test Document",
        content="Test content"
    )

def test_document_creation(sample_document):
    assert sample_document.name == "Test Document"

Architecture Guidelines¶

Domain Layer¶

Keep domain models pure and focused
Use Pydantic for validation
No infrastructure dependencies
Protocol-based repository interfaces

Application Layer¶

Use dependency injection
Keep route handlers thin
Delegate to use cases
Clear request/response models

Infrastructure Layer¶

Implement repository protocols
Handle external service interactions
Proper error handling and retries
Logging for debugging

Code Organization¶

Follow the existing structure:

julee/
├── api/               # FastAPI application
│   ├── routers/       # Route handlers
│   └── tests/         # API tests
├── domain/            # Domain layer
│   ├── models/        # Domain models
│   ├── repositories/  # Repository protocols
│   └── use_cases/     # Business logic
├── repositories/      # Repository implementations
│   ├── minio/         # MinIO storage
│   ├── memory/        # In-memory (testing)
│   └── temporal/      # Temporal activities
├── services/          # External services
├── workflows/         # Temporal workflows
└── docs/              # Documentation

Pull Requests¶

Create a feature branch:
```
git checkout -b my-feature
```
Make your changes, don’t forget tests
Ensure all tests pass:
```
pytest
ruff check .
mypy .
```
Commit with clear messages. Use the imperative mood, first line short.
Push and create PR:
```
git push origin feature/my-feature
```

Documentation¶

Update documentation for:

New features
API changes
Configuration options
Architecture changes

Build docs locally:

cd docs
make html
open _build/html/index.html

Or use autobuild for live reload:

sphinx-autobuild docs docs/_build/html

Code Review¶

All PRs require review. Reviewers will check:

Code quality and style
Test coverage
Documentation updates
Architecture consistency
Breaking changes

Be responsive to feedback and iterate on your PR.

License and IP¶

By contributing, you agree that your contributions will belong to Pyx Holdings Pty. Ltd. who reserve all rights, including the right to distribute your contribution under the GPL.