Jararaca Microservice Framework

Overview

Jararaca is an async-first microservice framework designed to simplify the development of distributed systems. It provides a comprehensive set of tools for building robust, scalable, and maintainable microservices with a focus on developer experience and type safety.

Key Features

REST API Development

Easy-to-use interfaces for building REST APIs
Automatic request/response validation
Type-safe endpoints with FastAPI integration
Automatic OpenAPI documentation generation

Message Bus Integration

Topic-based message bus for event-driven architecture
Support for both worker and publisher patterns
Built-in message serialization and deserialization
Easy integration with AIO Pika for RabbitMQ

Distributed WebSocket

Room-based WebSocket communication
Distributed broadcasting across multiple backend instances
Automatic message synchronization between instances
Built-in connection management and room handling

Task Scheduling

Cron-based task scheduling
Support for overlapping and non-overlapping tasks
Distributed task execution
Easy integration with message bus for task distribution

TypeScript Integration

Automatic TypeScript interface generation
Command-line tool for generating TypeScript types
Support for REST endpoints, WebSocket events, and message bus payloads
Type-safe frontend-backend communication
@ExposeType decorator - Explicitly expose types for TypeScript generation without needing them in endpoints

Hexagonal Architecture

Clear separation of concerns
Business logic isolation from infrastructure
Easy testing and maintainability
Dependency injection for flexible component management

Observability

Built-in OpenTelemetry integration
Distributed tracing support
Logging and metrics collection
Performance monitoring capabilities

Quick Start

Installation

pip install jararaca

Basic Usage

from jararaca import Microservice, create_http_server
from jararaca.presentation.http_microservice import HttpMicroservice

# Define your microservice
app = Microservice(
    providers=[
        # Add your providers here
    ],
    controllers=[
        # Add your controllers here
    ],
    interceptors=[
        # Add your interceptors here
    ],
)

# Create HTTP server
http_app = HttpMicroservice(app)
web_app = create_http_server(app)

Running the Service

# Run as HTTP server
jararaca server app:http_app

# Run as message bus worker
jararaca worker app:app

# Run as scheduler
jararaca scheduler app:app

# Generate TypeScript interfaces
jararaca gen-tsi app.main:app app.ts

Documentation

For detailed documentation, please visit our documentation site.

Examples

Check out the examples directory for complete working examples of:

REST API implementation
WebSocket usage
Message bus integration
Task scheduling
TypeScript interface generation

Contributing

Contributions are welcome! Please read our contributing guidelines for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Release files for jararaca 0.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jararaca 0.5.1
File	Size	Uploaded
jararaca-0.5.1.tar.gz	463.1 kB	Aug 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for jararaca 0.5.1
File	Interpreter	ABI	Platform	Reset
jararaca-0.5.1-py3-none-any.whl 175.7 kB Aug 14, 2026	Python 3	none	any	Details

Total release size: 638.7 kB

Release files / jararaca-0.5.1.tar.gz

Download URL	jararaca-0.5.1.tar.gz
Size	463.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`6e1aaca80a0abb9eba9bc59116074399ddd47b182d30898d2a5a4465d9cd5de7`
BLAKE2b-256 checksum How to use checksums	`d127dcd868e233cd3184d946ae781fe3f6ab15c70a29e2d2d61a1e6d7abc3006`
Upload date	Aug 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.4.0 CPython/3.14.4 Linux/6.18.44-1-lts`

Release files / jararaca-0.5.1-py3-none-any.whl

Download URL	jararaca-0.5.1-py3-none-any.whl
Size	175.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`cf2adb27d33be43bd7245b304b6f06248942a10ca5c29b48169b5228b3eb76c5`
BLAKE2b-256 checksum How to use checksums	`1c9ccb722e97a1f626e4928c25869f8b66669723958b797a9ed84b6c80cd6c64`
Upload date	Aug 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.4.0 CPython/3.14.4 Linux/6.18.44-1-lts`