Flaxon 0.3.0 and Teloce-Py 0.3.0 are available on PyPI. Release instructions are maintained on this site; source links identify the framework snapshot. Check version and upgrade guidance.

Framework source · Markdown

Architecture

Overview

Flaxon is an ASGI-first Python web framework that sits between clients and your application services.

The framework is responsible for:

• Protocol dispatch
• Routing
• Request and response handling
• Middleware execution
• Request validation
• Exception handling
• Application lifecycle events
• Extension and plugin registration

Business logic belongs in your application's services, models, and domain layer—not inside the framework.

Layered Architecture

┌──────────────────────────────────────────────────────┐
│                  Client Layer                         │
│  Web • Mobile • CLI • Desktop • Third-Party APIs     │
└──────────────────────────────┬───────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────┐
│                Flaxon Framework                      │
│  Protocol → Routing → Middleware → Endpoint          │
└──────────────────────────────┬───────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────┐
│               Application Layer                      │
│  Routes • Services • Schemas • Events • Business     │
└──────────────────────────────┬───────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────┐
│             Infrastructure Layer                     │
│ Database • Cache • Storage • Queue • Email • Redis   │
└──────────────────────────────────────────────────────┘

ASGI Application

Flaxon fully implements the ASGI 3.0 specification.

Supported protocols include:

• HTTP — Request and response handling
• WebSocket — Real-time communication
• Lifespan — Startup and shutdown events

Example:

async def __call__(self, scope, receive, send):
    if scope["type"] == "http":
        await self._handle_http(scope, receive, send)

    elif scope["type"] == "websocket":
        await self._handle_websocket(scope, receive, send)

    elif scope["type"] == "lifespan":
        await self._handle_lifespan(receive, send)

Request Lifecycle

Every incoming request follows the same processing pipeline.

        Client
           │
           ▼
    ASGI Server
           │
           ▼
      Flaxon App
           │
           ▼
      Middleware
           │
           ▼
        Router
           │
           ▼
 Parameter Resolution
           │
           ▼
 Validation (Schemas)
           │
           ▼
 Endpoint Function
           │
           ▼
 Response Conversion
           │
           ▼
 Exception Handling
           │
           ▼
      ASGI Response

Processing steps:

1. The ASGI server creates a request scope.
2. Flaxon receives the request.
3. Middleware executes.
4. The router matches the path and HTTP method.
5. Path parameters are converted.
6. Request data is validated.
7. The endpoint function executes.
8. Python objects are converted into HTTP responses.
9. Exceptions are translated into appropriate HTTP responses.
10. The ASGI server sends the response back to the client.

Core Components

Application

The Flaxon class is the heart of the framework.

It manages:

• Configuration
• Routes
• Middleware
• Application state
• Lifecycle events
• Jinax integration
• WebSocket rooms
• Debugger
• Extensions and plugins

Router

The router is responsible for:

• Route registration
• URL matching
• URL generation
• HTTP method dispatch
• Path parameter conversion

Route templates use angle-bracket parameters:

/users/<int:id>

Request

The Request object provides convenient access to:

• HTTP method
• URL
• Path
• Headers
• Cookies
• Query parameters
• Path parameters
• Request body

Body methods are asynchronous for maximum performance.

Response

Flaxon automatically converts common Python objects into HTTP responses.

Supported return values include:

• dict
• list
• str
• bytes
• Response
• Streaming responses

Middleware

Middleware wraps the application and executes in order.

Typical middleware includes:

• CORS
• Security headers
• Authentication
• Rate limiting
• Request IDs
• Logging
• Compression

Validation

Flaxon uses declarative schemas for request validation.

Validation automatically:

• Parses incoming data
• Converts types
• Validates values
• Returns HTTP 422 responses when validation fails
• Injects validated objects into route handlers

WebSockets

Flaxon includes first-class WebSocket support.

Features include:

• Room management
• Broadcasting
• Connection lifecycle
• JSON messaging
• Custom managers

Jinax

Jinax is Flaxon's optional server-side template engine.

It provides:

• HTML rendering
• Template inheritance
• Auto reload
• Jinja2 compatibility

Dependency Direction

Client
      │
      ▼
HTTP / WebSocket
      │
      ▼
Flaxon Framework
      │
      ▼
Application Services
      │
      ▼
Repositories
      │
      ▼
Infrastructure

Business services should avoid depending directly on Request objects whenever possible.

Keeping services framework-independent makes them reusable from:

• HTTP endpoints
• WebSocket handlers
• Scheduled jobs
• CLI commands
• Background workers
• Unit tests

Concurrency Model

Flaxon is built on Python's asyncio event loop.

All request handling is asynchronous and optimized for high-concurrency I/O workloads.

Best Practices

✔ Use asynchronous database drivers.

✔ Await all I/O operations.

✔ Prefer async HTTP clients.

✔ Keep endpoints non-blocking.

Avoid:

• Long CPU-intensive operations
• Blocking file operations
• Synchronous database drivers
• Blocking network requests

For CPU-intensive work, use background workers, task queues, or process pools to keep the event loop responsive.

Architecture Principles

Flaxon is designed around a few core principles:

• Async-first — Built for modern asynchronous applications.
• Technology-neutral — Use any database, frontend, ORM, or client.
• Minimal magic — Explicit APIs that are easy to understand.
• Scalable structure — Start with a single file and grow into large applications.
• Composable — Add middleware, plugins, and extensions only when needed.
• Developer-friendly — Helpful debugging, validation, and tooling out of the box.