Routing — Overview

UDIOT provides two complementary routing mechanisms: RouteConventionEngine for scanning a directory tree and converting its file structure into routes, and AutoRouter for automatically registering those routes at runtime. API conventions (APIRouteModule, describeAPIConventions) standardize how route modules export HTTP method handlers.

Key Concepts

File-based routing. Files inside a pages/ directory map to URL paths using Next.js-style conventions. index.ts files map to the directory path, [param].ts segments become :param dynamic parameters, and [...slug].ts files become catch-all (*) routes.

Special files. _layout.ts and layout.ts wrap child routes in a layout component. _middleware.ts files are applied to all routes in that directory and its children.

API routes. Files inside pages/api/ are treated as API routes. They export named functions for each HTTP method: GET, POST, PUT, PATCH, DELETE. A default export handles all methods.

AutoRouter. The AutoRouter class extends the UDIOT Router. It calls RouteConventionEngine.scanRoutes() at initialization, dynamically imports each route module, and registers the handlers. It optionally enables hot reload via chokidar.

Controllers. For controller-based routing (using @Controller, @Get, @Post, etc.), pass controller classes to createWebServer({ controllers }) from @tagna/udiot/web, or mount one on an existing Express app with toExpressRouter from @tagna/udiot/server.

How the Layers Fit Together

File system (pages/)
        │
        ▼
RouteConventionEngine.scanRoutes()
        │ RouteConvention[]
        ▼
AutoRouter.registerConvention()
        │  dynamic import + wrap with MiddlewarePipeline
        ▼
Router (addRoute / match / handle)

For controller-based routing:

@Controller + @Get/@Post/... decorators
        │
        ▼
createWebServer({ controllers })  or  toExpressRouter(Controller)
        │
        ▼
Express route handlers

See Also

• conventions.md — RouteConventionEngine, file-to-route mapping
• auto-router.md — AutoRouter, createAutoRouter, hot reload
• api-conventions.md — APIRouteModule, APIRouteHandler, describeAPIConventions