How rezwanahmedsami/catzilla works
Project Type & Purpose
• Catzilla is an open-source, high-performance Python web framework with a minimal, event-driven C core.
• It is not a full-stack application but a library/SDK—users write Python apps using Catzilla’s Python API, which bridges to a C HTTP engine.
Top-Level Architectural Domains
a. User Application Layer
b. Python Framework Layer
c. C Extension & Native Core Layer
d. External & System Dependencies
Main Components
a. User Application
• The user’s Python code (e.g., @app.get handlers in examples/)
b. Python Framework
• python/catzilla/ (App, Router, decorators, response types)
• setup.py / pyproject.toml (package metadata)
c. C Extension & Core
• src/python/module.c (CPython bindings)
• src/core/server.c/h (event-driven HTTP server)
• src/core/router.c/h (advanced trie router)
• deps/libuv (event loop)
• deps/llhttp (HTTP parser)
• unity (C test framework)
d. External & System
• Operating system (network stack, threads)
• Python interpreter (GIL, C-API)
• Build tools (CMake, compilers)
• Optional: benchmarks harness, test runners
Relationships & Data Flow
1. User App → Python Framework (method calls, decorator registration)
2. Python Framework → C Extension (PyObject API calls)
3. C Extension → C Core (function pointers, event callbacks)
4. C Core ↔ libuv (I/O readiness, timers)
5. C Core ↔ llhttp (HTTP parsing)
6. C Core → Router (trie lookup) → Handler callback back to Python
7. Python Framework → return value serialization → network response
Architectural Patterns & Principles
• Hybrid C/Python layering for zero-overhead performance
• Event-driven I/O (reactor pattern via libuv)
• Trie-based routing (O(log n) lookup)
• Decorator API for zero-boilerplate routing
• GIL-aware concurrency: long native operations release GIL if necessary
• Zero dependencies in Python layer
Technology & Framework Labels
• Python 3.8+ compatibility
Final Checklist
• [ ] Clear component labels and file-group callouts
• [ ] Annotations for critical architectural patterns (reactor, trie routing, decorator API)