fastapi-route 0.1.0__py3-none-any.whl

fastapi_route-0.1.0.dist-info/METADATA

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: fastapi-route
+Version: 0.1.0
+Summary: File-based routing for FastAPI with automatic route discovery
+Author-email: Your Name <you@example.com>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.23.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: watchdog>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: ruff>=0.0.260; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Requires-Dist: httpx>=0.24.0; extra == "test"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/fastapi-router/fastapi-router/main/docs/logo.png" alt="FastAPI Router Logo" width="300">
+</p>
+
+# FastAPI Router
+
+A file-based routing system for FastAPI — build APIs with the simplicity of files and folders, not decorators.
+
+**[Full Documentation](https://inject3r.github.io/fastapi-router)** — Complete API reference, advanced guides, and examples
+
+<br/>
+
+## Why FastAPI Router?
+
+Stop writing decorators. Start organizing your API with files and folders. Just drop Python files in directories — each file becomes an endpoint, each directory becomes a route segment. Dynamic parameters? Use `[param]` directories. Route groups? Use `(group)` directories. It's that simple.
+
+## Features
+
+- **File-Based Routing**: Routes defined by directory structure — no decorators needed
+- **Dynamic Routes**: `[user_id]` directories automatically become `{user_id}` parameters
+- **Cache-All Routes**: `[...slug]` captures unlimited path segments
+- **Route Groups**: `(auth)` directories organize code without affecting URLs
+- **Hot Reload**: Instant rebuild on file changes during development
+- **Production Build Cache**: Pre-compiled routes for lightning-fast startup
+- **Beautiful Error Pages**: Syntax highlighting, line numbers, and helpful suggestions
+- **Custom Handlers**: Bring your own `docs.py` and `not-found.py`
+- **Custom Middleware**: Intercept requests with `middleware.py`
+- **Static File Serving**: Drop files in `/public` — served automatically
+- **Built-in Documentation**: Auto-generated API docs at `/docs`
+- **CLI Tools**: `init`, `build`, `run`, `dev`, `clean`, `status` commands
+- **Zero Config**: Works out of the box — but fully customizable when you need it
+- **Type Hints**: Full typing support for excellent IDE autocompletion
+
+## Installation
+
+```bash
+pip install fastapi-router
+```
+
+With development dependencies:
+
+```bash
+pip install fastapi-router[dev]
+```
+
+## Quick Start
+
+### 1. Initialize a new project
+
+```bash
+fastapi-router init
+```
+
+### 2. Create your first route
+
+```python
+# routes/index.py
+from fastapi_router import Request
+
+def GET(request: Request):
+    return {"message": "Hello World!"}
+
+def POST(request: Request):
+    data = await request.json()
+    return {"received": data}
+```
+
+### 3. Add a dynamic route
+
+```python
+# routes/users/[user_id]/route.py
+from fastapi_router import Request
+
+def GET(request: Request, user_id: int):
+    return {"user_id": user_id, "name": f"User {user_id}"}
+```
+
+### 4. Run your API
+
+```bash
+# Development mode (with hot reload)
+fastapi-router dev
+
+# Production mode (requires build first)
+fastapi-router build
+fastapi-router run
+```
+
+Visit `http://localhost:8000/docs` for auto-generated documentation.
+
+## How It Works
+
+```text
+routes/
+├── index.py                    → GET /, POST /
+├── about/
+│   └── route.py                → GET /about
+├── users/
+│   ├── route.py                → GET /users, POST /users
+│   ├── [user_id]/
+│   │   └── route.py            → GET /users/{user_id}, PUT /users/{user_id}
+│   └── [user_id]/posts/
+│       └── route.py            → GET /users/{user_id}/posts
+├── docs/
+│   └── [...slug]/
+│       └── route.py            → GET /docs/*
+└── (auth)/                     # Route group (ignored in URL)
+    └── profile/
+        └── route.py            → GET /profile
+```
+
+## CLI Commands
+
+| Command                 | Description                                 |
+| ----------------------- | ------------------------------------------- |
+| `fastapi-router init`   | Create a new project with default structure |
+| `fastapi-router build`  | Compile routes into production cache        |
+| `fastapi-router run`    | Start production server (requires build)    |
+| `fastapi-router dev`    | Start development server with hot reload    |
+| `fastapi-router clean`  | Remove build cache                          |
+| `fastapi-router status` | Show build cache information                |
+
+## Customization
+
+### Configuration (`config.py`)
+
+```python
+app_name = "My API"
+debug = False
+cors_enabled = True
+cors_origins = ["https://example.com"]
+
+server = {
+    "host": "0.0.0.0",
+    "port": 8080,
+    "workers": 4
+}
+
+logging = {
+    "level": "INFO",
+    "format": "[%Y-%m-%d %H:%M:%S]",
+    "color": True
+}
+
+commands = {
+    "deploy": "fastapi-router build && rsync -avz .cache/ deploy/"
+}
+```
+
+### Custom Middleware (`middleware.py`)
+
+```python
+from fastapi_router import Request
+
+async def middleware(request: Request, call_next):
+    # Log every request
+    print(f"{request.method} {request.path}")
+
+    # Continue to the route handler
+    response = await call_next(request)
+
+    # Add custom header
+    response.headers["X-Powered-By"] = "FastAPI Router"
+
+    return response
+```
+
+### Custom 404 Page (`not-found.py`)
+
+```python
+from fastapi_router import Request, HTMLResponse
+
+def handler(request: Request, context):
+    routes = context.get_routes()
+
+    return HTMLResponse(content=f"""
+    <!DOCTYPE html>
+    <html>
+    <head><title>404 - Not Found</title></head>
+    <body>
+        <h1>404 - Page Not Found</h1>
+        <p>{request.path} does not exist</p>
+        <p>Total routes: {len(routes)}</p>
+        <a href="/">Go Home</a>
+    </body>
+    </html>
+    """, status_code=404)
+```
+
+## Documentation
+
+For complete documentation, API reference, and advanced usage examples, visit:
+
+**[https://inject3r.github.io/fastapi-router](https://inject3r.github.io/fastapi-router)**
+
+The documentation includes:
+
+- Detailed API reference for all modules and classes
+- Advanced routing patterns and best practices
+- Configuration options and their effects
+- Error handling strategies
+- Migration guides from traditional FastAPI
+- Production deployment guides
+
+## Repository
+
+Source code and issue tracking:
+
+**[https://github.com/inject3r/fastapi-router](https://github.com/inject3r/fastapi-router)**
+
+## Requirements
+
+- Python 3.9+
+- FastAPI 0.100.0+
+- Uvicorn 0.23.0+
+
+## Running Tests
+
+```bash
+# Run all tests with coverage
+./scripts/test.sh
+
+# Clean test output files
+./scripts/test_clean.sh
+```
+
+## Project Structure
+
+```text
+your-project/
+├── routes/                 # Your API routes (file-based)
+│   ├── index.py
+│   └── ...
+├── public/                 # Static files (served at /)
+│   ├── css/
+│   ├── js/
+│   └── images/
+├── config.py               # Application configuration
+├── middleware.py           # Custom middleware (optional)
+├── docs.py                 # Custom documentation (optional)
+├── not-found.py            # Custom 404 page (optional)
+└── .cache/                 # Build cache (auto-generated)
+```
+
+## Why No Decorators?
+
+FastAPI Router was built for developers who think in terms of files and directories, not decorators and route registrations. Just create files — they become endpoints. Create directories — they become route segments. Use `[param]` for dynamic parameters. Use `(group)` for organization.
+
+No decorators. No route registration. Just files.
+
+## License
+
+This project is licensed under the MIT License.
+
+## Author
+
+**Abolfazl Hosseini**
+
+- Email: tryuzr@gmail.com
+- GitHub: [@inject3r](https://github.com/inject3r)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Acknowledgments
+
+- [FastAPI](https://fastapi.tiangolo.com/) - The amazing web framework
+- All contributors and users of this project

fastapi_route-0.1.0.dist-info/RECORD

@@ -0,0 +1,58 @@
+fastapi_route-0.1.0.dist-info/licenses/LICENSE,sha256=NAC7SVw_jEw0g6RMa8GpLp2UQG23Wm8n28zBHHZFDYo,5
+fastapi_router/__init__.py,sha256=-PukPobOAT285s77hzDde9jWZDtt62VM56jXR_PIrMg,841
+fastapi_router/app.py,sha256=3bJufHnLEUChReILbLWuuY-rXqN0VDAY7xsoUA3OY_I,10800
+fastapi_router/constants.py,sha256=blF47Ep8zXzzz3E63fSP_tanCR9-aPVJA5GedNLcMLA,2879
+fastapi_router/exceptions.py,sha256=3zcOXmvsex7LJewjhBdZjpfiAhnfTqlyyD5qTc_dUXw,7167
+fastapi_router/request.py,sha256=gC1D2KmbN-qCNCGHva3T7wyzlW5nGflh80CAk8hd0-s,6927
+fastapi_router/response.py,sha256=PUMKNgwSp90NFqT-e-BMlRDp-5R186X2IlVfHID_t2A,5985
+fastapi_router/types.py,sha256=PlYAoGIsNfpqGiJxCDBJLsX1gPUUtGnHXx4Itbpm9Ys,7949
+fastapi_router/version.py,sha256=Pru0BlFBASFCFo7McHdohtKkUtgMPDwbGfyUZlE2_Vw,21
+fastapi_router/build/__init__.py,sha256=91l0wsho3C4oxb0DpZPja0icvsIm0DjfAwSHy1T2I7s,156
+fastapi_router/build/builder.py,sha256=Ila_spVDLisULCivjBvR-eLRwIr8qscmMqJEXf0OCXo,9355
+fastapi_router/build/cache.py,sha256=eu2qV6EDC1hJECMArqD_OE17u_UMJiqRlGw56jhh_K4,13100
+fastapi_router/build/loader.py,sha256=m6TANs0QHmpwXH70uY8dLmm_TsCl457eAkDP920h6eQ,3103
+fastapi_router/cli/commands.py,sha256=vZRGrkjjDcp3p4gvPbFSsaPiB6D8EE9sCKzAiwU_bDE,14443
+fastapi_router/config/loader.py,sha256=yUfjKp3m-4D7PtFqKSZD0YZ9VPS92JDYeb_AQgNQx-I,15656
+fastapi_router/config/py_loader.py,sha256=dG_YVf01f-btrEIS26wfc4ndW81KAePry0Y73rgAwhQ,9519
+fastapi_router/config/schema.py,sha256=CGIJZ9LwBNvu7RdKm8v1_2mZMWIXwP4Mulr_YQtIevw,2885
+fastapi_router/config/validator.py,sha256=8od8V3L8duRUqrEiVoMeLZIba8QoYEofECefCmN10MI,6301
+fastapi_router/core/builder.py,sha256=0dI4XpUFsZ10sGsd1RjL52aI_knmbC_CSZwq4SYgIbA,28054
+fastapi_router/core/lifecycle.py,sha256=M7V4p7rVAhPU67qWhRyvqWYkAhgYkjdDod5cW49g81o,3303
+fastapi_router/core/registry.py,sha256=X0nEgqBnfF3p9OCjEWVLy7_MFcpaCetcavtuf1WAx64,4991
+fastapi_router/core/scanner.py,sha256=FCPXZODXCzXbps4hzzUCmjSxufo9VKevv61TlAdRdRc,12324
+fastapi_router/core/validator.py,sha256=mX8mEcGKBK92-8zNy2I9EA-9IJvw3R8zwmrqk_Sv3qM,12899
+fastapi_router/custom/__init__.py,sha256=YfyZWKvceo5u5tpzC5ouNdUJL4tOb__gXhmezHxFqr0,186
+fastapi_router/custom/context.py,sha256=kJxjrCHk5VFVbM3iTTY00UsyW9dAIUctrf1YQpaxTaY,5666
+fastapi_router/custom/error_page.py,sha256=BIq4hGktQv1DX3I6o-7XO6ckcuKVNhWa84AKkIA48U4,8511
+fastapi_router/custom/loader.py,sha256=t42QCEObG_qBJZdVNc8bdZ6-x7inlaj0-BumUWgBhJA,10723
+fastapi_router/custom/validator.py,sha256=y_zeV3JUROjUfAHqzuhN6Q4ouBcm23kJDzcmpg9M5eU,8794
+fastapi_router/decorators/__init__.py,sha256=LGfYrvPdU76S6dmahJm-bm5ZhWITMUTudg0Io0j-ywE,142
+fastapi_router/decorators/methods.py,sha256=MH60kMKXNTMcxCEoHf4PBIlU0wjkNPNcINoC-tbHrKQ,3483
+fastapi_router/dev/config_watcher.py,sha256=9mIkf83jQ3rz2P2tUkJPA2rtt4l5qh1n47lEU5YZWTg,4797
+fastapi_router/dev/error_handler.py,sha256=yGmJdVT8zIBQTqYulZiFpO707wuoayhKilTaomku2uk,10950
+fastapi_router/dev/error_page.py,sha256=sXkduQJHzJSO_384cn2MfPwpWJ_f0iYY_GwwykXf6ec,27384
+fastapi_router/dev/server.py,sha256=NT5IsYD3LP2HU0NoQulKMozz7GCOj1xJlpZO99e46X4,19707
+fastapi_router/docs/__init__.py,sha256=MX-gTxmOwh9nAsleVrcNe_gc1YY_-5r0eVe0ZiL1SqI,233
+fastapi_router/docs/collector.py,sha256=CWiE6R-Ew8ZlmmJribXmtC1e42uX544K8BbAwi_bOXY,8882
+fastapi_router/docs/generator.py,sha256=mvqsidetpKGWSqRVhGQzLllfx9K5Kc6swbqPOle2JGM,20772
+fastapi_router/docs/renderer.py,sha256=i3jdo0GQr26SeKfg99Z_5CD-hGrddfT-Qc1iAOY-Mbs,5628
+fastapi_router/middleware/custom.py,sha256=fReInKnLCsCb1RC3jR7jYkP_WjPZFKWY_rPpPgW2YWM,7670
+fastapi_router/middleware/manager.py,sha256=GRY5XDHssDeZ1I9z7ahmCxpX12u42OKY9DGWQ32uxwA,3403
+fastapi_router/middleware/validator.py,sha256=xc38xzvdUptDJS_wPMDZr42QYSI8nFoiq1Laj_6H-cc,6426
+fastapi_router/routing/compiler.py,sha256=iYBTM5ISmoYiMRgSiUiUluiCg91NVvwccHbLD_hWPMk,2588
+fastapi_router/routing/filesystem.py,sha256=MaCS6YlyG8Kif-hupK2WxS5Mwcexhb5zktR15qLFtxM,2141
+fastapi_router/routing/matcher.py,sha256=_ARdCy7vFK28xDAqzYRlqetUXIm62PDFW8_QuUxIsEw,3179
+fastapi_router/routing/parser.py,sha256=ZtXBY_qgqS7jbzad7pM8bWy3MT3HwUaa8-T_4jkSQSw,4623
+fastapi_router/routing/router.py,sha256=yY_Jnx0n6B1wWYReKH5sQLNVSFvW_0cJnB8_H5mffQo,3122
+fastapi_router/static/__init__.py,sha256=kAiHJFMrgBfzYZezazcz-gB0PncZAUGUpxIFxnkS6rQ,242
+fastapi_router/static/directory_listing.py,sha256=c8VoT4_2bdlhOCpolBbVY8IbCd5XtvE9hZT6mq6BrbA,6751
+fastapi_router/static/handler.py,sha256=wW_o8CWrRSTuNoWymvehYgBlZJk5R6HA0j0w156eLbo,8219
+fastapi_router/static/middleware.py,sha256=i-RIB1ugXlCaaqSEnjxpG59EqLwacW9LJQova7ZGutA,4536
+fastapi_router/utils/imports.py,sha256=HK6mSaHxcncLsY42tfyKaKVCq92jW41uar1X2LsqcEU,2387
+fastapi_router/utils/logger.py,sha256=Fb6P2y6bWxKluiwWBAzcP1RNZwb_2hXtRlREjq6EjUI,9253
+fastapi_router/utils/paths.py,sha256=3KnHY7AV6GH3flDkkTYBKpD6BkJ_F0rvE1j-AEH_kT4,1977
+fastapi_route-0.1.0.dist-info/METADATA,sha256=lgcSOE2q7FLM9V35qHrS-NIeQDFk_2XqudD-cE2FMhU,8847
+fastapi_route-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fastapi_route-0.1.0.dist-info/entry_points.txt,sha256=uas8lkNWaE-YcKwF7CS3j27mXu5c4U27iiIy5DB3aOI,68
+fastapi_route-0.1.0.dist-info/top_level.txt,sha256=hZIWNXAsKb6zyMweL16KPzeKS7XqBsrH6AGxS7ZT0I4,15
+fastapi_route-0.1.0.dist-info/RECORD,,

fastapi_route-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fastapi_route-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fastapi-router = fastapi_router.cli.commands:main

fastapi_route-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1 @@
+lorem

fastapi_route-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fastapi_router

fastapi_router/__init__.py

@@ -0,0 +1,34 @@
+"""FastAPI Router - File-based routing for FastAPI"""
+
+from .app import create_app, FastAPIRouterApp
+from .version import __version__
+from .routing.router import Router
+from .request import Request
+from .response import Response, JSONResponse, HTMLResponse, PlainTextResponse, RedirectResponse
+from .exceptions import (
+    HTTPException,
+    BadRequestException,
+    UnauthorizedException,
+    ForbiddenException,
+    NotFoundException,
+    MethodNotAllowedException,
+)
+
+__all__ = [
+    "create_app",
+    "FastAPIRouterApp",
+    "__version__",
+    "Router",
+    "Request",
+    "Response",
+    "JSONResponse",
+    "HTMLResponse",
+    "PlainTextResponse",
+    "RedirectResponse",
+    "HTTPException",
+    "BadRequestException",
+    "UnauthorizedException",
+    "ForbiddenException",
+    "NotFoundException",
+    "MethodNotAllowedException",
+]

fastapi_router/app.py

@@ -0,0 +1,280 @@
+"""
+Main application factory for FastAPI Router.
+
+This module provides the core application class that builds and runs the
+FastAPI application. It handles route discovery, caching, configuration,
+and lifecycle management.
+
+The application can run in two modes:
+- Development: Routes are scanned from filesystem on each build
+- Production: Routes are loaded from build cache for faster startup
+
+Features:
+- Automatic route discovery from filesystem
+- Build cache support for production
+- Custom documentation endpoint
+- Lifecycle hooks for startup/shutdown
+- Configurable logging levels
+"""
+
+import sys
+from pathlib import Path
+from typing import Optional, Any, Dict, List
+
+from .config.loader import ConfigLoader
+from .core.registry import RouteRegistry
+from .core.builder import AppBuilder
+from .core.lifecycle import LifecycleManager
+from .routing.filesystem import FileSystemRouter
+from .build import CacheLoader
+from .types import RouteInfo
+from .utils.logger import logger, Logger
+
+
+class FastAPIRouterApp:
+    """
+    Main application class for FastAPI Router.
+    
+    This class orchestrates the entire application lifecycle:
+    1. Load configuration
+    2. Discover routes (from filesystem or cache)
+    3. Build the FastAPI application
+    4. Set up middleware and handlers
+    5. Run the server
+    
+    The application can be used in two ways:
+    - Direct execution: app = FastAPIRouterApp(); app.run()
+    - As ASGI app: app = FastAPIRouterApp(); app = app.build()
+    
+    Args:
+        config_path: Optional path to configuration file
+        enable_docs: Whether to enable the /docs endpoint
+        custom_docs_template: Custom HTML template for documentation
+        use_cache: Use build cache for routes (production mode)
+        is_production: Run in production mode (reduced logging)
+    """
+    
+    def __init__(self, config_path: Optional[str] = None, enable_docs: bool = True, 
+                 custom_docs_template: Optional[str] = None, use_cache: bool = False, 
+                 is_production: bool = False):
+        self.config_path = config_path
+        self.config = ConfigLoader.load(config_path)
+        
+        # Apply settings from config or constructor args
+        self.enable_docs = enable_docs if hasattr(self.config, 'docs_enabled') else enable_docs
+        self.custom_docs_template = custom_docs_template or getattr(self.config, 'custom_docs_template', None)
+        self.use_cache = use_cache
+        self.is_production = is_production
+        
+        # Configure logger based on mode
+        Logger.set_production_mode(is_production)
+        
+        # Initialize core components
+        self.registry = RouteRegistry()
+        self.lifecycle = LifecycleManager()
+        self._fastapi_app = None
+        self._is_built = False
+    
+    def _load_handler_from_file(self, file_path: Path, handler_name: str):
+        """
+        Dynamically load a handler function from a Python file.
+        
+        This is used in production mode to load route handlers from the
+        original source files when using build cache.
+        
+        Args:
+            file_path: Path to the route file
+            handler_name: Name of the handler function (e.g., "GET")
+            
+        Returns:
+            Handler function if found, None otherwise
+        """
+        import importlib.util
+        import sys
+        
+        try:
+            # Convert file path to module name
+            module_name = str(file_path).replace("/", ".").replace("\\", ".").replace(".py", "")
+            
+            # Use cached module if available
+            if module_name in sys.modules:
+                module = sys.modules[module_name]
+            else:
+                spec = importlib.util.spec_from_file_location(module_name, file_path)
+                if spec is None or spec.loader is None:
+                    return None
+                module = importlib.util.module_from_spec(spec)
+                sys.modules[module_name] = module
+                spec.loader.exec_module(module)
+            
+            return getattr(module, handler_name, None)
+        except Exception as e:
+            if not self.is_production:
+                logger.error(f"Failed to load handler {handler_name} from {file_path}: {e}")
+            return None
+    
+    def build(self) -> Any:
+        """
+        Build and return the FastAPI application.
+        
+        This method performs the actual application construction:
+        1. Discover routes (filesystem or cache)
+        2. Register routes in the registry
+        3. Build the FastAPI app with all middleware and handlers
+        4. Set up lifecycle events
+        
+        Returns:
+            Configured FastAPI application instance
+        """
+        if self._is_built and self._fastapi_app:
+            return self._fastapi_app
+        
+        if not self.is_production:
+            logger.info("Building FastAPI Router application...")
+        
+        try:
+            routes: List[RouteInfo] = []
+            routes_metadata: List[Dict[str, Any]] = []
+            
+            # Try to load from cache if production mode
+            if self.use_cache:
+                cache_loader = CacheLoader(Path.cwd())
+                routes_metadata = cache_loader.load_routes_metadata()
+                if routes_metadata:
+                    if not self.is_production:
+                        logger.info(f"Loading {len(routes_metadata)} routes from cache")
+                else:
+                    if not self.is_production:
+                        logger.warning("Cache invalid or missing, falling back to filesystem scan")
+                    self.use_cache = False
+            
+            # Fall back to filesystem scan if cache not available
+            if not self.use_cache:
+                router = FileSystemRouter(self.config.route_dir)
+                routes = router.scan()
+                if not self.is_production:
+                    logger.info(f"Discovered {len(routes)} routes via filesystem scan")
+            else:
+                # Load handlers from source files for cached routes
+                for meta in routes_metadata:
+                    handler = self._load_handler_from_file(
+                        Path(meta['file_path']), 
+                        meta['method']
+                    )
+                    if handler is None:
+                        if not self.is_production:
+                            logger.error(f"Failed to load handler for {meta['method']} {meta['path']}")
+                        continue
+                    
+                    route = RouteInfo(
+                        path=meta['path'],
+                        method=meta['method'],
+                        handler=handler,
+                        file_path=Path(meta['file_path']),
+                        is_dynamic=meta['is_dynamic'],
+                        param_names=meta['param_names']
+                    )
+                    routes.append(route)
+                
+                if not self.is_production:
+                    logger.info(f"Loaded {len(routes)} routes from cache")
+            
+            # No routes found - cannot start
+            if not routes:
+                logger.warning("No routes found")
+                return None
+            
+            # Register all routes
+            for route in routes:
+                self.registry.register(route)
+            
+            # Build the FastAPI application
+            builder = AppBuilder(self.config, self.registry, self.enable_docs, self.custom_docs_template)
+            self._fastapi_app = builder.build()
+            
+            # Set up lifecycle hooks
+            self.lifecycle.setup(self._fastapi_app)
+            
+            self._is_built = True
+            
+            # Log success
+            if not self.is_production:
+                logger.info(f"Application built with {len(routes)} routes")
+                if self.enable_docs:
+                    logger.info(f"Documentation available at /docs")
+            
+            return self._fastapi_app
+            
+        except Exception as e:
+            logger.error(f"Build failed: {e}")
+            if not self.is_production:
+                import traceback
+                traceback.print_exc()
+            raise
+    
+    def run(self, host: str = "127.0.0.1", port: int = 8000, reload: bool = False):
+        """
+        Run the application using uvicorn server.
+        
+        Args:
+            host: Host address to bind to
+            port: Port number to listen on
+            reload: Enable auto-reload (development mode)
+        """
+        try:
+            import uvicorn
+        except ImportError:
+            logger.error("uvicorn not installed. Please install it: pip install uvicorn")
+            return
+        
+        app = self.build()
+        
+        if app is None:
+            logger.error("No routes found, cannot start server")
+            return
+        
+        mode = "development" if reload else "production"
+        logger.info(f"Starting {mode} server on http://{host}:{port}")
+        
+        if not reload and self.use_cache:
+            logger.info("Running in production mode with build cache")
+        
+        # Reduce uvicorn log noise in production
+        if self.is_production:
+            import logging
+            log_config = uvicorn.config.LOGGING_CONFIG
+            log_config["loggers"]["uvicorn"]["level"] = "WARNING"
+            log_config["loggers"]["uvicorn.access"]["level"] = "WARNING"
+            log_config["loggers"]["uvicorn.error"]["level"] = "WARNING"
+            uvicorn.run(app, host=host, port=port, reload=reload, 
+                       log_config=log_config, access_log=False)
+        else:
+            uvicorn.run(app, host=host, port=port, reload=reload)
+
+
+def create_app(config_path: Optional[str] = None, enable_docs: bool = True, 
+               custom_docs_template: Optional[str] = None, use_cache: bool = False, 
+               is_production: bool = False) -> Any:
+    """
+    Factory function to create a FastAPI Router application.
+    
+    This is a convenience wrapper around FastAPIRouterApp for use with
+    ASGI servers like uvicorn directly.
+    
+    Example:
+        app = create_app()
+        # Use with uvicorn: uvicorn.run(app)
+    
+    Args:
+        config_path: Optional path to configuration file
+        enable_docs: Enable documentation endpoint
+        custom_docs_template: Custom HTML template for docs
+        use_cache: Use build cache (production mode)
+        is_production: Run in production mode
+    
+    Returns:
+        Configured FastAPI application instance
+    """
+    app_wrapper = FastAPIRouterApp(config_path, enable_docs, custom_docs_template, 
+                                   use_cache, is_production)
+    return app_wrapper.build()