Kerly is an AI assistant that helps you find your next meal, guided by nutrition-first recommendations inspired by USDA dietary guidance, built on a Python (Litestar) backend.
- Python – Core programming language for backend.
- Litestar – High-performance ASGI framework for modern Python web apps.
- Advanced Alchemy – SQLAlchemy integration (async) + migrations tooling.
- REST – Resource-oriented APIs over HTTP with JSON.
- PostgreSQL – Advanced open-source relational database known for reliability.
- Redis – In-memory data store for message brokering.
- Celery – Distributed task queue for handling asynchronous background jobs.
- Flower – Real-time monitoring for Celery workers.
- uv – Ultra-fast Python package and project manager.
- ruff – Extremely fast Python linter and code formatter.
- ty – Fast, type-safe Python type checker.
- Docker Desktop – Provides Docker Engine and Docker Compose.
- mise – Manages tool versions.
- Task – Task runner designed for modern workflows.
- pre-commit – Manages and runs automated Git hooks.
Run the setup script to install dependencies and configure the environment:
./setup.shNote: if you get permission denied, run
chmod +x setup.shthen retry./setup.sh.
After it finishes, start services in separate terminals:
task backend:dev
task worker:dev
task beat:devOptionally, monitoring:
task flower:dev-
Verify Docker is available:
docker --version docker compose version docker info
-
Install mise:
curl https://mise.run | shIf this fails, see the official install docs.
-
Install the project toolchain:
mise install -y
-
Install pre-commit hooks:
pre-commit install
-
Copy the example environment files:
cp .env.example .env cp backend/.env.example backend/.env
-
Pull database image:
task infra:pull
-
Start database service:
task db:up
-
Install backend dependencies:
task backend:install
-
Start backend:
task backend:dev
-
Create an initial admin user:
task backend:create-admin-user
-
Start background worker:
task worker:dev
-
Start periodic task scheduler:
task beat:dev
-
Start monitoring (optional):
task flower:dev
The services will be available at:
This project is pre-configured for VS Code (or any fork like Cursor or Windsurf) to provide a seamless development experience:
- Type Checking: Since we use
ty, the"python.languageServer"setting is set to"None"in.vscode/settings.json. This avoids running two language servers simultaneously when the Python extension is enabled (see official ty configuration).
This project uses a canonical rule system to manage AI/LLM coding rules, first oriented to VS Code + GitHub Copilot (and compatible agents like Cursor or Antigravity).
- Always-on standards live in
.github/instructions/. - Task-specific workflows live in
.github/skills/. - Prompt files (workflow entry points) live in
.github/prompts/.
This is an opinionated deployment recommendation that has worked well in production, but you are free to deploy Kerly using any providers or infrastructure that fit your needs.
Kerly has been deployed successfully with the backend + database on Render.
See full deployment details in docs/deployment.md.
This project uses Task to simplify common development workflows. The main
Taskfile.yml in the project root provides commands for:
- Managing the Docker environment (for example, building, starting, or stopping services).
- Running development tasks within the
backendservice (such as linting, formatting, or testing). - Managing background workers (Celery worker and beat).
To list all available tasks, run:
task --listThis project uses GitHub Actions for continuous integration and validation:
- PR Validation: Enforce PR title conventions and limit PR size.
- CI Workflow: Run tests and linting on the backend.
For detailed information about our CI/CD workflows, see the workflows documentation.
All versioned changes are documented on the GitHub Releases page.
This project is licensed under the MIT License.