# rezwanahmedsami/catzilla architecture

> Architecture diagram of the GitHub repository rezwanahmedsami/catzilla, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rezwanahmedsami/catzilla
- Repository: https://github.com/rezwanahmedsami/catzilla

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application Layer
    subgraph "User Application Layer"
        direction TB
        UA1["examples/hello_world/main.py"]:::pythonLayer
        UA2["examples/error_handling/comprehensive_error_handling.py"]:::pythonLayer
    end

    %% Python Framework Layer
    subgraph "Python Framework Layer"
        direction TB
        PF1["python/catzilla/app.py"]:::pythonLayer
        PF2["python/catzilla/routing.py"]:::pythonLayer
        PF3["python/catzilla/c_router.py"]:::pythonLayer
        PF4["python/catzilla/fast_router.py"]:::pythonLayer
        PF5["python/catzilla/response.py"]:::pythonLayer
        PF6["python/catzilla/types.py"]:::pythonLayer
        PM1["setup.py"]:::pythonLayer
        PM2["pyproject.toml"]:::pythonLayer
    end

    %% C Extension & Bindings
    subgraph "C Extension & Bindings"
        direction TB
        CE["src/python/module.c"]:::cLayer
    end

    %% C Core & Native Core Layer
    subgraph "C Core & Native Core"
        direction TB
        subgraph "HTTP Engine"
            direction TB
            HE1["src/core/server.c"]:::cLayer
            HE2["src/core/server.h"]:::cLayer
            HE3["src/core/windows_compat.h"]:::cLayer
        end
        subgraph "Routing Engine"
            direction TB
            RE1["src/core/router.c"]:::cLayer
            RE2["src/core/router.h"]:::cLayer
        end
    end

    %% Dependencies
    subgraph "Dependencies"
        direction TB
        D1["deps/libuv/"]:::external
        D2["deps/llhttp/"]:::external
        D3["deps/unity/"]:::external
    end

    %% External & System
    subgraph "External & System"
        direction TB
        ES1["Operating System"]:::external
        ES2["Python Interpreter"]:::external
        ES3["CMake/Compilers"]:::external
    end

    %% Quality Assurance
    subgraph "Quality Assurance"
        direction TB
        QA1["tests/python/"]:::external
        QA2["tests/c/"]:::external
    end

    %% Performance & Benchmarks
    subgraph "Performance Benchmarks"
        direction TB
        PB1["benchmarks/run_all.sh"]:::external
        PB2["benchmarks/servers/catzilla_server.py"]:::external
    end

    %% CI/CD Workflows
    subgraph "CI/CD Workflows"
        direction TB
        CI1[".github/workflows/build.yml.txt"]:::external
        CI2[".github/workflows/ci.yml"]:::external
        CI3[".github/workflows/docs.yml"]:::external
        CI4[".github/workflows/release.yml"]:::external
    end

    %% Connections
    UA1 -->|"decorator_registration"| PF1
    UA2 -->|"decorator_registration"| PF1
    PF1 -->|"PyObject*_calls"| CE
    CE -->|"function_pointers"| HE1
    HE1 -->|"I/O_events"| D1
    D1 -->|"I/O_ready"| HE1
    HE1 -->|"HTTP_parsing"| D2
    D2 -->|"parsed_requests"| HE1
    HE1 -->|"trie_lookup"| RE1
    RE1 -->|"handler_callback"| CE
    CE -->|"return_PyObject*"| PF1
    PF1 -->|"serialize_response"| PF5
    PF5 -->|"raw_buffer"| HE1
    ES1 -->|"network_stack"| HE1
    ES2 -->|"GIL_C-API"| CE
    ES3 -->|"build_process"| HE1

    %% Side components not directly in main flow
    CE --> QA2
    PF1 --> QA1
    HE1 --> QA2
    PB1 --> PB2
    PB2 --> HE1
    CI1 --> HE1
    CI2 --> CE
    CI3 --> PF1
    CI4 --> PM1

    %% Click Events
    click UA1 "https://github.com/rezwanahmedsami/catzilla/blob/main/examples/hello_world/main.py"
    click UA2 "https://github.com/rezwanahmedsami/catzilla/blob/main/examples/error_handling/comprehensive_error_handling.py"
    click PF1 "https://github.com/rezwanahmedsami/catzilla/blob/main/python/catzilla/app.py"
    click PF2 "https://github.com/rezwanahmedsami/catzilla/blob/main/python/catzilla/routing.py"
    click PF3 "https://github.com/rezwanahmedsami/catzilla/blob/main/python/catzilla/c_router.py"
    click PF4 "https://github.com/rezwanahmedsami/catzilla/blob/main/python/catzilla/fast_router.py"
    click PF5 "https://github.com/rezwanahmedsami/catzilla/blob/main/python/catzilla/response.py"
    click PF6 "https://github.com/rezwanahmedsami/catzilla/blob/main/python/catzilla/types.py"
    click PM1 "https://github.com/rezwanahmedsami/catzilla/blob/main/setup.py"
    click PM2 "https://github.com/rezwanahmedsami/catzilla/blob/main/pyproject.toml"
    click CE "https://github.com/rezwanahmedsami/catzilla/blob/main/src/python/module.c"
    click HE1 "https://github.com/rezwanahmedsami/catzilla/blob/main/src/core/server.c"
    click HE2 "https://github.com/rezwanahmedsami/catzilla/blob/main/src/core/server.h"
    click HE3 "https://github.com/rezwanahmedsami/catzilla/blob/main/src/core/windows_compat.h"
    click RE1 "https://github.com/rezwanahmedsami/catzilla/blob/main/src/core/router.c"
    click RE2 "https://github.com/rezwanahmedsami/catzilla/blob/main/src/core/router.h"
    click D1 "https://github.com/rezwanahmedsami/catzilla/tree/main/deps/libuv/"
    click D3 "https://github.com/rezwanahmedsami/catzilla/tree/main/deps/unity/"
    click PB1 "https://github.com/rezwanahmedsami/catzilla/blob/main/benchmarks/run_all.sh"
    click PB2 "https://github.com/rezwanahmedsami/catzilla/blob/main/benchmarks/servers/catzilla_server.py"
    click CI1 "https://github.com/rezwanahmedsami/catzilla/blob/main/.github/workflows/build.yml.txt"
    click CI2 "https://github.com/rezwanahmedsami/catzilla/blob/main/.github/workflows/ci.yml"
    click CI3 "https://github.com/rezwanahmedsami/catzilla/blob/main/.github/workflows/docs.yml"
    click CI4 "https://github.com/rezwanahmedsami/catzilla/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef pythonLayer fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef cLayer fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
```
