# zedeus/nitter architecture

> Architecture diagram of the GitHub repository zedeus/nitter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zedeus/nitter
- Repository: https://github.com/zedeus/nitter

## Overview

1. **What the system is**
   Nitter is a Nim-based server application that renders Twitter/X content on the server and serves lightweight HTML, RSS, and related endpoints to browsers. The browser talks only to Nitter; Nitter talks to Twitter’s unofficial endpoints on the backend.

2. **Runtime and top-level entrypoint**
   The application starts in `src/nitter.nim`, with configuration and constants in `src/config.nim` and `src/consts.nim`. The runtime is a single web service process, typically deployed behind a reverse proxy and backed by Redis.

3. **Request routing layer**
   HTTP endpoints are split by feature under `src/routes/`: timelines, profiles/status pages, search, lists, RSS, media, embeds, preferences, resolver, debug, broadcast, and unsupported routes. `src/routes/router_utils.nim` holds shared routing helpers. This layer maps incoming paths and query parameters to feature-specific handlers.

4. **Twitter-facing fetch layer**
   The backend’s external dependency is Twitter/X. Fetching and request orchestration live in `src/api.nim`, `src/apiutils.nim`, `src/http_pool.nim`, `src/query.nim`, and authentication/session handling in `src/auth.nim`. These modules encapsulate outbound requests, session tokens, and shared HTTP behavior so route code does not directly manage low-level network details.

5. **Parsing and Twitter response models**
   Twitter responses are transformed into internal data structures by `src/parser.nim`, `src/parserutils.nim`, `src/tid.nim`, and `src/types.nim`. There is also a substantial `src/experimental/parser/` and `src/experimental/types/` subtree, which indicates an alternate or evolving parsing pipeline for newer Twitter GraphQL/session payloads and related object types.

6. **Rendering layer**
   Presentation is separated into `src/views/`, with view modules for timelines, profiles, tweets, search, lists, status pages, RSS, embeds, broadcasts, preferences, and about pages. These views assemble the final HTML/text responses from parsed domain data, while `src/views/renderutils.nim` provides shared rendering helpers.

7. **Preference and user-state handling**
   User-facing preferences are handled by `src/prefs.nim` and `src/prefs_impl.nim`, with routes in `src/routes/preferences.nim` and views in `src/views/preferences.nim`. The repo also references HMAC/cookie/session configuration in the README, so the app maintains a small amount of user state even though it remains a lightweight frontend.

8. **Caching and persistence boundary**
   `src/redis_cache.nim` is the main persistence/caching boundary. The README makes Redis/Valkey mandatory for caching, and future account data. This means the service is stateless at the application layer except for Redis-backed cache/state and the configured session credentials.

9. **Static assets and client-side behavior**
   The `public/` directory contains the shipped CSS themes, fonts, JavaScript, markdown content, robots, and web manifest. Client-side JS is intentionally minimal and only used for specific UX features such as infinite scroll or media playback (`public/js/infiniteScroll.js`, `public/js/hlsPlayback.js`). Styling is mostly generated from `src/sass/`, and markdown content is rendered into static pages.

10. **Build and deployment model**
   The project is built with Nim (`nitter.nimble`, `config.nims`), with separate Docker and ARM64 Dockerfiles, plus `docker-compose.yml` for running Nitter alongside Redis. The README and workflows show CI for tests and Docker image builds, and the repo includes helper tools for generating CSS, markdown, and session tokens.

11. **Test coverage**
   The `tests/` directory contains Python-based integration/behavior tests for major user flows: profiles, tweets, threads, quotes, cards, search, timeline, and tweet media. This suggests the architecture is validated end-to-end at the rendered-output layer, not just at isolated function level.

12. **Primary data flow for architecture diagrams**
   The core flow is: browser request → route handler → fetch/auth/query layer → Twitter response → parser/types → view renderer → HTML/RSS response. Redis sits alongside the fetch/parsing path as a cache/state store, while the `public/` assets are served as static resources supporting the rendered pages.

13. **Important architectural boundary**
   The key boundary is between the public-facing Nitter server and Twitter: all Twitter access is centralized in backend modules, and the browser never directly connects to Twitter. That separation is the main reason the service can remove JavaScript-heavy client tracking and keep pages lightweight.

Main entry points: [`src/api.nim`](https://github.com/zedeus/nitter/blob/master/src/api.nim) (API client), [`src/routes/router_utils.nim`](https://github.com/zedeus/nitter/blob/master/src/routes/router_utils.nim) (Route helpers), [`src/nitter.nim`](https://github.com/zedeus/nitter/blob/master/src/nitter.nim) (Nitter main), [`src/views/renderutils.nim`](https://github.com/zedeus/nitter/blob/master/src/views/renderutils.nim) (Render utils)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App entry"]
  node_node_entry["Nitter main<br/>server entrypoint<br/>[nitter.nim]"]
  node_node_config["Config<br/>settings<br/>[config.nim]"]
  node_node_consts["Consts<br/>constants<br/>[consts.nim]"]
end

subgraph group_group_routes["HTTP routes"]
  node_node_router["Route helpers<br/>routing utils<br/>[router_utils.nim]"]
  node_node_timeline["Timeline<br/>route handler<br/>[timeline.nim]"]
  node_node_profile["Status & profile<br/>route handler<br/>[status.nim]"]
  node_node_search["Search<br/>route handler<br/>[search.nim]"]
  node_node_media["Media<br/>route handler<br/>[media.nim]"]
  node_node_rss["RSS<br/>route handler<br/>[rss.nim]"]
  node_node_prefs_route["Preferences<br/>route handler<br/>[preferences.nim]"]
end

subgraph group_group_backend["Twitter backend"]
  node_node_api["API client<br/>fetch layer<br/>[api.nim]"]
  node_node_http["HTTP pool<br/>http runtime<br/>[http_pool.nim]"]
  node_node_auth["Auth<br/>session handling<br/>[auth.nim]"]
  node_node_query["Query<br/>request shaping<br/>[query.nim]"]
  node_node_parser["Parser<br/>response parsing<br/>[parser.nim]"]
  node_node_types["Types<br/>domain models<br/>[types.nim]"]
  node_node_redis[("Redis cache<br/>cache/state<br/>[redis_cache.nim]")]
end

subgraph group_group_views["Rendering"]
  node_node_views["Render utils<br/>render helpers<br/>[renderutils.nim]"]
  node_node_timeline_view["Timeline view<br/>template<br/>[timeline.nim]"]
  node_node_profile_view["Profile view<br/>template<br/>[profile.nim]"]
  node_node_tweet_view["Tweet view<br/>template<br/>[tweet.nim]"]
  node_node_search_view["Search view<br/>template<br/>[search.nim]"]
end

subgraph group_group_assets["Assets & tools"]
  node_node_public["Public assets<br/>static assets"]
  node_node_sass["Sass sources<br/>style source"]
  node_node_tests["Integration tests<br/>behavior tests"]
  node_node_tools["Build tools<br/>tooling"]
end

node_node_entry -->|"loads"| node_node_config
node_node_entry -->|"registers"| node_node_router
node_node_entry -->|"connects"| node_node_redis
node_node_router -->|"dispatches"| node_node_timeline
node_node_router -->|"dispatches"| node_node_profile
node_node_router -->|"dispatches"| node_node_search
node_node_router -->|"dispatches"| node_node_media
node_node_router -->|"dispatches"| node_node_rss
node_node_router -->|"dispatches"| node_node_prefs_route
node_node_timeline -->|"fetches"| node_node_api
node_node_profile -->|"fetches"| node_node_api
node_node_search -->|"builds"| node_node_query
node_node_search -->|"fetches"| node_node_api
node_node_media -->|"fetches"| node_node_api
node_node_rss -->|"fetches"| node_node_api
node_node_prefs_route -->|"stores"| node_node_redis
node_node_api -->|"uses"| node_node_auth
node_node_api -->|"uses"| node_node_http
node_node_api -->|"feeds"| node_node_parser
node_node_parser -->|"produces"| node_node_types
node_node_parser -->|"consults"| node_node_redis
node_node_timeline -->|"renders"| node_node_timeline_view
node_node_profile -->|"renders"| node_node_profile_view
node_node_profile -->|"renders"| node_node_tweet_view
node_node_search -->|"renders"| node_node_search_view
node_node_timeline_view -->|"uses"| node_node_views
node_node_profile_view -->|"uses"| node_node_views
node_node_tweet_view -->|"uses"| node_node_views
node_node_search_view -->|"uses"| node_node_views
node_node_public -->|"served by"| node_node_entry
node_node_sass -->|"builds into"| node_node_public
node_node_tools -->|"generates"| node_node_sass
node_node_tools -->|"renders"| node_node_public
node_node_tests -->|"exercises"| node_node_entry
node_node_tests -->|"asserts"| node_node_views

click node_node_entry "https://github.com/zedeus/nitter/blob/master/src/nitter.nim"
click node_node_config "https://github.com/zedeus/nitter/blob/master/src/config.nim"
click node_node_consts "https://github.com/zedeus/nitter/blob/master/src/consts.nim"
click node_node_router "https://github.com/zedeus/nitter/blob/master/src/routes/router_utils.nim"
click node_node_timeline "https://github.com/zedeus/nitter/blob/master/src/routes/timeline.nim"
click node_node_profile "https://github.com/zedeus/nitter/blob/master/src/routes/status.nim"
click node_node_search "https://github.com/zedeus/nitter/blob/master/src/routes/search.nim"
click node_node_media "https://github.com/zedeus/nitter/blob/master/src/routes/media.nim"
click node_node_rss "https://github.com/zedeus/nitter/blob/master/src/routes/rss.nim"
click node_node_prefs_route "https://github.com/zedeus/nitter/blob/master/src/routes/preferences.nim"
click node_node_api "https://github.com/zedeus/nitter/blob/master/src/api.nim"
click node_node_http "https://github.com/zedeus/nitter/blob/master/src/http_pool.nim"
click node_node_auth "https://github.com/zedeus/nitter/blob/master/src/auth.nim"
click node_node_query "https://github.com/zedeus/nitter/blob/master/src/query.nim"
click node_node_parser "https://github.com/zedeus/nitter/blob/master/src/parser.nim"
click node_node_types "https://github.com/zedeus/nitter/blob/master/src/types.nim"
click node_node_redis "https://github.com/zedeus/nitter/blob/master/src/redis_cache.nim"
click node_node_views "https://github.com/zedeus/nitter/blob/master/src/views/renderutils.nim"
click node_node_timeline_view "https://github.com/zedeus/nitter/blob/master/src/views/timeline.nim"
click node_node_profile_view "https://github.com/zedeus/nitter/blob/master/src/views/profile.nim"
click node_node_tweet_view "https://github.com/zedeus/nitter/blob/master/src/views/tweet.nim"
click node_node_search_view "https://github.com/zedeus/nitter/blob/master/src/views/search.nim"
click node_node_public "https://github.com/zedeus/nitter/tree/master/public"
click node_node_sass "https://github.com/zedeus/nitter/tree/master/src/sass"
click node_node_tests "https://github.com/zedeus/nitter/tree/master/tests"
click node_node_tools "https://github.com/zedeus/nitter/tree/master/tools"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_entry,node_node_config,node_node_consts toneBlue
class node_node_router,node_node_timeline,node_node_profile,node_node_search,node_node_media,node_node_rss,node_node_prefs_route toneAmber
class node_node_api,node_node_http,node_node_auth,node_node_query,node_node_parser,node_node_types,node_node_redis toneMint
class node_node_views,node_node_timeline_view,node_node_profile_view,node_node_tweet_view,node_node_search_view toneRose
class node_node_public,node_node_sass,node_node_tests,node_node_tools toneIndigo
```

## Components

### App entry

Process startup, configuration, and runtime wiring.

- [Nitter main](https://github.com/zedeus/nitter/blob/master/src/nitter.nim): server entrypoint · Starts the single web service and wires runtime behavior. · `src/nitter.nim`
- [Config](https://github.com/zedeus/nitter/blob/master/src/config.nim): settings · Application configuration and constants. · `src/config.nim`
- [Consts](https://github.com/zedeus/nitter/blob/master/src/consts.nim): constants · Shared constant values used across the service. · `src/consts.nim`

### HTTP routes

Request handlers that map public endpoints to feature flows.

- [Route helpers](https://github.com/zedeus/nitter/blob/master/src/routes/router_utils.nim): routing utils · Shared routing utilities used by endpoint modules. · `src/routes/router_utils.nim`
- [Timeline](https://github.com/zedeus/nitter/blob/master/src/routes/timeline.nim): route handler · Home feed and timeline endpoints. · `src/routes/timeline.nim`
- [Status & profile](https://github.com/zedeus/nitter/blob/master/src/routes/status.nim): route handler · Profile, status, and tweet page handlers. · `src/routes/status.nim`
- [Search](https://github.com/zedeus/nitter/blob/master/src/routes/search.nim): route handler · Search endpoints and query routing. · `src/routes/search.nim`
- [Media](https://github.com/zedeus/nitter/blob/master/src/routes/media.nim): route handler · Media-related endpoints and proxying flows. · `src/routes/media.nim`
- [RSS](https://github.com/zedeus/nitter/blob/master/src/routes/rss.nim): route handler · RSS feed endpoints. · `src/routes/rss.nim`
- [Preferences](https://github.com/zedeus/nitter/blob/master/src/routes/preferences.nim): route handler · Preference endpoints and form handling. · `src/routes/preferences.nim`

### Twitter backend

Outbound access, auth, parsing, and data models for Twitter/X.

- [API client](https://github.com/zedeus/nitter/blob/master/src/api.nim): fetch layer · High-level outbound request orchestration to Twitter/X. · `src/api.nim`
- [HTTP pool](https://github.com/zedeus/nitter/blob/master/src/http_pool.nim): http runtime · Shared HTTP client and connection management. · `src/http_pool.nim`
- [Auth](https://github.com/zedeus/nitter/blob/master/src/auth.nim): session handling · Authentication, session tokens, and request credentials. · `src/auth.nim`
- [Query](https://github.com/zedeus/nitter/blob/master/src/query.nim): request shaping · Query construction and parameter shaping for outbound calls. · `src/query.nim`
- [Parser](https://github.com/zedeus/nitter/blob/master/src/parser.nim): response parsing · Transforms Twitter responses into internal structures. · `src/parser.nim`
- [Types](https://github.com/zedeus/nitter/blob/master/src/types.nim): domain models · Core internal data structures for parsed Twitter content. · `src/types.nim`
- [Redis cache](https://github.com/zedeus/nitter/blob/master/src/redis_cache.nim): cache/state · Redis-backed cache and persistent lightweight state. · `src/redis_cache.nim`

### Rendering

View templates and shared rendering helpers.

- [Render utils](https://github.com/zedeus/nitter/blob/master/src/views/renderutils.nim): render helpers · Shared rendering helpers used by view modules. · `src/views/renderutils.nim`
- [Timeline view](https://github.com/zedeus/nitter/blob/master/src/views/timeline.nim): template · Renders timeline and feed pages. · `src/views/timeline.nim`
- [Profile view](https://github.com/zedeus/nitter/blob/master/src/views/profile.nim): template · Renders profile and status pages. · `src/views/profile.nim`
- [Tweet view](https://github.com/zedeus/nitter/blob/master/src/views/tweet.nim): template · Renders tweet, thread, quote, and media fragments. · `src/views/tweet.nim`
- [Search view](https://github.com/zedeus/nitter/blob/master/src/views/search.nim): template · Renders search results and search UI. · `src/views/search.nim`

### Assets & tools

Static client assets, styling sources, tests, and build helpers.

- [Public assets](https://github.com/zedeus/nitter/tree/master/public): static assets · Shipped CSS, JS, fonts, markdown, and manifest files. · `public`
- [Sass sources](https://github.com/zedeus/nitter/tree/master/src/sass): style source · Stylesheet source tree for themes and component styling. · `src/sass`
- [Integration tests](https://github.com/zedeus/nitter/tree/master/tests): behavior tests · End-to-end tests covering rendered user flows. · `tests`
- [Build tools](https://github.com/zedeus/nitter/tree/master/tools): tooling · Helpers for CSS generation, markdown rendering, and session setup. · `tools`

## Connections

- Nitter main → Config: loads · Startup reads configuration values.
- Nitter main → Route helpers: registers · Main process wires HTTP routing.
- Nitter main → Redis cache: connects · Runtime attaches the cache/state backend.
- Route helpers → Timeline: dispatches · Shared routing helpers feed timeline endpoints.
- Route helpers → Status & profile: dispatches · Routes status and profile pages.
- Route helpers → Search: dispatches · Routes search requests.
- Route helpers → Media: dispatches · Routes media endpoints.
- Route helpers → RSS: dispatches · Routes RSS endpoints.
- Route helpers → Preferences: dispatches · Routes preference updates.
- Timeline → API client: fetches · Timeline handlers request Twitter data.
- Status & profile → API client: fetches · Profile/status handlers request Twitter data.
- Search → Query: builds · Search handlers shape outbound queries.
- Search → API client: fetches · Search results come from backend requests.
- Media → API client: fetches · Media handlers obtain upstream content.
- RSS → API client: fetches · RSS feeds are generated from upstream data.
- Preferences → Redis cache: stores · Preferences use Redis-backed state where needed.
- API client → Auth: uses · Outbound access relies on auth/session material.
- API client → HTTP pool: uses · Requests are executed through the shared HTTP pool.
- API client → Parser: feeds · Fetched responses are handed to parsers.
- Parser → Types: produces · Parsing yields internal domain models.
- Parser → Redis cache: consults · Parser and fetch flow may consult cached state.
- Timeline → Timeline view: renders · Timeline routes render through timeline views.
- Status & profile → Profile view: renders · Profile/status routes render profile views.
- Status & profile → Tweet view: renders · Status pages compose tweet/thread views.
- Search → Search view: renders · Search routes render search views.
- Timeline view → Render utils: uses · Views rely on shared rendering helpers.
- Profile view → Render utils: uses · Views rely on shared rendering helpers.
- Tweet view → Render utils: uses · Views rely on shared rendering helpers.
- Search view → Render utils: uses · Views rely on shared rendering helpers.
- Public assets → Nitter main: served by · Static assets support the public web app.
- Sass sources → Public assets: builds into · Sass sources compile into shipped CSS assets.
- Build tools → Sass sources: generates · Tools include CSS generation helpers.
- Build tools → Public assets: renders · Tools produce markdown and session-related artifacts.
- Integration tests → Nitter main: exercises · Integration tests drive the full server flows.
- Integration tests → Render utils: asserts · Tests validate rendered output paths.
