Velocix

A learning project where I rebuilt Starlette's core patterns to understand how modern async Python web frameworks work.

---

What This Is

• A study project built during my B.Tech CSE studies
• Heavily inspired by Starlette's architecture and patterns
• An exercise in understanding ASGI and async Python
• A way to learn performance optimization concepts
• A minimal framework experiment

What This Is NOT

• A production-ready framework
• Faster than existing solutions (FastAPI/Starlette)
• Something you should use instead of established frameworks
• A unique or groundbreaking implementation

What I Learned

• How ASGI works under the hood
• Async Python patterns and best practices
• Why performance optimization requires actual measurement, not assumptions
• How routing, middleware, and request handling work internally
• That framework overhead is usually negligible compared to database queries and business logic
• The importance of honest benchmarking and documentation

---

📦 Installation

Prerequisites

• Python 3.10 or higher
• pip

Install Dependencies

pip install -r requirements.txt

Core Dependencies

• orjson - Fast JSON serialization
• msgspec - Fast validation and serialization
• httptools - HTTP request parsing
• Any ASGI server (uvicorn, granian, hypercorn)

---

🚀 Quick Start

from velocix import Velocix
from velocix.core.response import JSONResponse

app = Velocix()

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

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    return {"user_id": user_id}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

---

🏗️ Code Structure

velocix/
├── core/           # Core ASGI application and routing (based on Starlette patterns)
├── http/           # HTTP utilities
├── middleware/     # Middleware implementations
├── security/       # Authentication and security utilities
├── validation/     # Request validation (msgspec)
├── websocket/      # WebSocket support
├── monitoring/     # Health checks and metrics
└── testing/        # Test client utilities

---

📚 Documentation

• API Reference - Complete API documentation
• User Guide - How to use Velocix features
• Security Guide - Security best practices
• Internals - Architecture details

---

🤝 Contributing

This is a learning project, but if you find it useful or want to suggest improvements, feel free to open an issue or PR.

---

🙏 Acknowledgments

This project is heavily inspired by:

• Starlette - Most patterns and architecture are based on Starlette's design
• FastAPI - For the elegant decorator-based API
• msgspec - For fast validation
• orjson - For efficient JSON serialization

Special thanks to the authors of these frameworks for their excellent documentation and open-source code that made this learning project possible.

---

📖 Learning Resources

If you want to build something similar, I recommend:

• Reading Starlette's source code (it's very well written)
• Understanding the ASGI specification
• Studying async Python patterns
• Actually measuring performance instead of assuming optimizations work

---

📄 License

MIT License - See LICENSE file for details

---

Built as a learning exercise by a CSE student

A minimal framework experiment - use Starlette or FastAPI for real projects.