# How Nitter Routes User Requests: A Deep Dive into the Jester Framework > Discover how Nitter routes user requests using the Jester framework. Explore URL pattern matching, modular routers, and endpoint dispatch for a fast, privacy-focused experience. - Repository: [Zed/nitter](https://github.com/zedeus/nitter) - Tags: deep-dive - Published: 2026-09-04 --- **Nitter routes user requests through the Jester web framework by registering modular routers in `src/nitter.nim` that match URL patterns against handlers in `src/routes/*.nim`, applying global middleware before dispatching to timeline, status, or media-specific endpoints.** Nitter is an open-source alternative Twitter frontend written in Nim, designed to provide a lightweight, privacy-focused interface to Twitter content. The application handles HTTP request routing through a modular architecture built on top of **Jester**, a Sinatra-inspired web framework for Nim. Understanding how Nitter routes user requests requires examining the bootstrap sequence in the main entry point and the specialized router modules that define URL patterns and handlers. ## Core Routing Architecture Nitter's request handling follows a six-stage pipeline that processes every HTTP request from configuration loading to response generation. The architecture separates concerns between bootstrap configuration, global middleware, and domain-specific routers. The routing flow operates as follows: 1. **Configuration Loading** – `src/nitter.nim` reads [`nitter.conf`](https://github.com/zedeus/nitter/blob/main/nitter.conf) and initializes the `Config` object with port, static directory, and binding address settings. 2. **Router Initialization** – Specialized functions like `createTimelineRouter(cfg)` and `createStatusRouter(cfg)` instantiate Jester router objects and register their route patterns. 3. **Global Middleware Execution** – A `before` block runs for every request, validating path formatting and applying user preferences via `applyUrlPrefs()`. 4. **Pattern Matching** – Jester scans registered routers (`router timeline`, `router status`, etc.) and selects the first pattern matching the request URL. 5. **Handler Execution** – The matched route handler fetches data from Twitter's GraphQL API, processes it through caching layers, and prepares the response. 6. **Response Rendering** – Handlers call `resp` or return rendered strings, which Jester transmits back to the client. ## Application Bootstrap and Router Initialization The central entry point `src/nitter.nim` orchestrates the entire routing infrastructure by creating and registering individual router modules. During startup, the application sequentially initializes fourteen distinct routers, each responsible for specific feature domains: ```nim createArticleRouter(cfg) createUnsupportedRouter(cfg) createResolverRouter(cfg) createPrefRouter(cfg) createTimelineRouter(cfg) createListRouter(cfg) createCommunityRouter(cfg) createStatusRouter(cfg) createSearchRouter(cfg) createMediaRouter(cfg) createEmbedRouter(cfg) createRssRouter(cfg) createBroadcastRouter(cfg) createSpaceRouter(cfg) createDebugRouter(cfg) ``` Each `createXRouter` function resides in its own file under `src/routes/` and internally invokes Jester's `router` macro to define a named router scope. The `settings` block configures global server parameters: ```nim settings: port = Port(cfg.port) staticDir = normalizedPath(cfg.staticDir) bindAddr = cfg.address ``` This modular approach allows Nitter to isolate functionality—timeline rendering, search operations, media handling, and administrative debug endpoints—into separate compilation units while maintaining a unified request handling pipeline. ## Global Middleware and Request Preprocessing Before any route-specific handler executes, all requests pass through a global `before` block defined in `src/nitter.nim`. This middleware layer enforces security constraints and loads user-specific settings: ```nim routes: before: if request.path.len == 0 or request.path[0] != '/': halt Http400 cond "." notin request.path or request.path == "/embed/Tweet.html" applyUrlPrefs() ``` The middleware performs three critical functions. First, it validates that every request path begins with a forward slash, rejecting malformed requests with HTTP 400. Second, it blocks direct file access attempts (paths containing dots) except for the Twitter widget compatibility endpoint [`/embed/Tweet.html`](https://github.com/zedeus/nitter/blob/main//embed/Tweet.html). Third, it invokes `applyUrlPrefs()` from `src/router_utils.nim` to parse cookies and URL parameters, establishing the user's theme, language, and content filtering preferences for the current request context. ## Router-Specific Implementation Examples Individual router modules in `src/routes/` contain the actual URL pattern definitions and handler logic. Each module follows a consistent structure: importing API utilities, defining the router scope, declaring `get` or `post` patterns with Jester's syntax, and calling helper functions from `src/api.nim` or `src/query.nim`. ### Timeline Router (`src/routes/timeline.nim`) The timeline router handles the majority of user-profile requests, mapping human-readable Twitter URLs to Nitter's rendering engine. It defines parameterized routes that capture dynamic segments: ```nim router timeline: get "/i/user/@user_id": respUserId() get "/intent/user": respUserId() get "/intent/follow/?": redirect("/" & request.params.getOrDefault("screen_name")) get "/@name/about/?": …renderAboutAccount… get "/@name/@kind/?": …renderUserList… get "/@name/?@tab?/?": …showTimeline… ``` The route `/@name/?@tab?/?` demonstrates Jester's pattern syntax. Dynamic segments prefixed with `@` capture URL components as variables accessible via `@"name"` notation within handlers. The optional segments (`?`) allow URLs like `/jack` or `/jack/with_replies` to match the same pattern. When processing a user timeline request, the handler constructs a **Query** object through `request.getQuery(@"tab", @"name", prefs)`, which specifies the timeline type (tweets, replies, media, articles, or search) and target user. For infinite-scroll functionality, the router detects the `@scroll` parameter and returns JSON fragments via `renderTweetSearch` or `renderTimelineTweets` instead of full HTML documents. ### Status Router (`src/routes/status.nim`) Individual tweet pages route through `src/routes/status.nim`, which validates identifiers and manages conversation threading: ```nim router status: get "/@name/status/@id/?": let id = @"id" if id.len > 19 or id.any(c => not c.isDigit): resp Http404, showError("Invalid tweet ID", cfg) … let conv = await getTweet(id, getCursor(), sort) … resp renderMain(html, request, cfg, prefs, title, …) ``` The handler validates tweet IDs (rejecting non-numeric strings or IDs exceeding 19 characters), then awaits `getTweet()` from `src/api.nim` to retrieve the tweet and its conversation thread. The router supports pagination of replies through a `scroll` parameter, streaming additional content as users navigate deep reply chains. ## Utility Layers and API Integration Beneath the router layer, Nitter relies on specialized utility modules to bridge HTTP requests with Twitter's internal APIs: - **`src/router_utils.nim`** – Provides `requestPrefs`, `getCursor`, and `applyUrlPrefs` for parsing user preferences and pagination tokens from URL parameters. - **`src/api.nim`** – Contains the core data fetching logic including `getTweet()`, `getGraphUserTweets()`, and `getGraphTweetSearch()`, handling GraphQL query construction and response caching. - **`src/query.nim`** – Defines the `Query` type and `initQuery()` functions, creating domain objects that encode filter criteria (user handles, search terms, media types) for the API layer. - **`src/views/*.nim`** – Houses Karax-based rendering functions like `renderMain()`, `renderTimelineTweets()`, and `renderConversation()` that transform API responses into HTML. This separation ensures that router files in `src/routes/` remain focused on URL pattern matching and HTTP-level concerns, while business logic and presentation details reside in dedicated modules. ## Summary - Nitter uses the **Jester** web framework to map HTTP requests to Nim handlers through declarative router blocks. - The main entry point in `src/nitter.nim` initializes fourteen specialized routers and configures global middleware that runs before every request. - Route patterns use Jester's `@parameter` syntax to capture dynamic URL segments, as seen in `/@name/?@tab?/?` in `src/routes/timeline.nim`. - Global preprocessing in the `before` block validates paths and loads user preferences via `applyUrlPrefs()` from `src/router_utils.nim`. - Individual routers delegate data fetching to `src/api.nim` (Twitter GraphQL integration) and rendering to `src/views/` modules, maintaining clean separation between routing, business logic, and presentation. ## Frequently Asked Questions ### How does Nitter handle dynamic URL parameters like usernames or tweet IDs? Nitter utilizes Jester's parameterized routing syntax where segments prefixed with `@` capture values from the URL path. For example, the pattern `"/@name/status/@id/?"` in `src/routes/status.nim` extracts the username as `@"name"` and the tweet identifier as `@"id"`, making these values available as string variables within the route handler for validation and API queries. ### What happens if a request doesn't match any defined route? If Jester cannot match the incoming URL against any registered router pattern, the framework automatically returns an HTTP 404 response. Additionally, Nitter's global `before` middleware in `src/nitter.nim` preemptively halts requests with `halt Http400` for malformed paths (such as those missing a leading slash or containing suspicious dot segments), providing an additional layer of request validation before pattern matching occurs. ### Can Nitter route requests differently based on user preferences? Yes, the routing pipeline supports preference-dependent behavior through the `applyUrlPrefs()` function executed in the global `before` block. This loads settings from cookies and URL parameters into a `Prefs` object that handlers pass to rendering functions. While the URL pattern matching remains consistent, the resulting content—such as theme selection, video autoplay settings, or content filtering—is applied dynamically based on these preferences. ### Which router handles the infinite scroll feature on timeline pages? The timeline router in `src/routes/timeline.nim` manages infinite scroll through conditional logic within the `showTimeline` handler. When the `@scroll` parameter is present in the request, instead of rendering a complete HTML page via `renderMain`, the handler returns JSON fragments using `renderTweetSearch` or `renderTimelineTweets`, allowing the frontend to append new content without a full page reload.