Examples & Recipes

Learn by doing

Every example below is a complete, runnable application. Clone the repo, pick a recipe, and have it running in seconds. Examples are organized by difficulty so you can progress at your own pace.

---

Run an Example

Get any example running in under a minute.

# Clone the repository
git clone https://github.com/jagadeesh32/cello.git
cd cello

# Set up the environment
python -m venv .venv && source .venv/bin/activate
pip install -e .

# Run any example
python examples/hello.py

Live reload for development

Add --reload to automatically restart when you edit the file:

python examples/hello.py --reload

---

Beginner

Start here if you are new to Cello. These examples cover the fundamentals with minimal code.

• Hello World

  ---

  Beginner { .md-tag }

  The simplest possible Cello app -- one route, one response. Understand the core pattern that every Cello application follows.

  Features used: App @app.get() dict response

  @app.get("/")
  def hello(request):
      return {"message": "Hello, World!"}
  

  Full Example

• REST API

  ---

  Beginner { .md-tag }

  Build a complete CRUD API with JSON validation, proper status codes, and error handling. The bread and butter of web development.

  Features used: Blueprint Response.json() request.json() status codes

  @api.post("/users")
  def create_user(request):
      data = request.json()
      return Response.json(user, status=201)
  

  Full Example

• Form Handling

  ---

  Beginner { .md-tag }

  Accept form submissions and file uploads with multipart support. Covers both URL-encoded forms and file uploads.

  Features used: request.form() multipart file uploads

  @app.post("/upload")
  def upload(request):
      file = request.files["document"]
      return {"filename": file.filename}
  

  Full Example

---

Intermediate

Ready to build real applications? These examples combine multiple Cello features into production-worthy patterns.

• Full-Stack App

  ---

  Intermediate { .md-tag }

  A complete web application with HTML templates, static file serving, form handling, and database integration. Everything you need for a traditional web app.

  Features used: Templates Static files Sessions Blueprints CSRF

  Full Example

• Microservices

  ---

  Intermediate { .md-tag }

  Break your application into independent services that communicate via HTTP and message queues. Includes service discovery and health checks.

  Features used: gRPC Message queues Health checks Circuit breaker OpenTelemetry

  Full Example

• Real-time Dashboard

  ---

  Intermediate { .md-tag }

  Live-updating dashboard using WebSocket and Server-Sent Events. Push data to connected clients in real time with automatic reconnection.

  Features used: WebSocket SSE Background tasks Prometheus metrics

  Full Example

---

Enterprise

Battle-tested patterns for large-scale production systems. These examples demonstrate how Cello handles the complexity of enterprise software.

• Multi-tenant SaaS

  ---

  Advanced { .md-tag }

  Tenant isolation at the middleware level with per-tenant databases, RBAC, and custom domain routing. The foundation for any SaaS product.

  Features used: Guards (RBAC) Middleware JWT Dependency injection Data partitioning

  Full Example

• API Gateway

  ---

  Advanced { .md-tag }

  A centralized API gateway with authentication, rate limiting, request transformation, and upstream load balancing. Control all traffic in one place.

  Features used: Rate limiting JWT auth CORS Circuit breaker Prometheus Request ID tracing

  Full Example

• Event Sourcing

  ---

  Advanced { .md-tag }

  Event-driven architecture with CQRS, an append-only event store, and the Saga pattern for distributed transaction coordination.

  Features used: Event store CQRS Saga pattern Background tasks Message queues

  Full Example

---

Example Architecture

How Cello's features layer together in a typical application.

graph LR
    A[Client Request] --> B[Middleware Pipeline]
    B --> C{Router}
    C -->|Blueprint A| D[Auth Guards]
    C -->|Blueprint B| E[Public Handler]
    D --> F[Handler + DI]
    F --> G[Response]
    E --> G
    G --> H[Middleware Pipeline]
    H --> I[Client Response]

    style A fill:#1A1A1A,stroke:#E65100,color:#FF9100
    style I fill:#1A1A1A,stroke:#E65100,color:#FF9100
    style C fill:#1A1A1A,stroke:#E65100,color:#FF9100
    style D fill:#1A1A1A,stroke:#424242,color:#ab47bc

---

Feature Matrix

Which features are demonstrated in each example?

Feature	Hello World	REST API	Forms	Full-Stack	Microservices	Dashboard	SaaS	Gateway	Events
Routing
Blueprints
Middleware
Guards / RBAC
JWT Auth
WebSocket / SSE
Dependency Injection
Background Tasks
Prometheus Metrics

---

More Examples

Browse the full collection of examples in the GitHub repository. Contributions are welcome -- see the Contributing Guide to add your own example.