Contributor Guide

This guide is for engineers who want to contribute to the CleverThis codebase. It covers setting up a local development environment, understanding the monorepo architecture, running the test suite, and the pull request process.

CleverThis is a monorepo. The main components are: a Next.js webapp (the dashboard UI), a Python FastAPI server (the gateway and management API), and cleveractors-core (the Python library that defines the Actor execution engine). All three live in the same repo and are developed together.

What's in this guide

• Dev Setup — installing dependencies and running the local stack
• Architecture — monorepo layout, component boundaries, and data flow
  • Webapp — Next.js frontend
  • API Server — FastAPI backend
  • cleveractors-core — actor execution library
• Testing — running tests with nox
• PR Process — how to open and land a pull request
• Code Style — ruff, pre-commit, and formatting conventions
• ADR Process — how architectural decisions are documented

Before you start

• Make sure you can run the local stack end-to-end before making changes. See Dev Setup.
• All contributions require a signed CLA. A bot will prompt you on your first PR.
• Check the issue tracker for issues tagged good-first-issue if you are looking for a place to start.