How zedeus/nitter works
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: api.nim API client · router_utils.nim Route helpers · nitter.nim Nitter main · renderutils.nim Render utils
Components 26
App entry
Process startup, configuration, and runtime wiring.
- Nitter main · Starts the single web service and wires runtime behavior.
src/nitter.nim - Config · Application configuration and constants.
src/config.nim - Consts · Shared constant values used across the service.
src/consts.nim
HTTP routes
Request handlers that map public endpoints to feature flows.
- Route helpers · Shared routing utilities used by endpoint modules.
src/routes/router_utils.nim - Timeline · Home feed and timeline endpoints.
src/routes/timeline.nim - Status & profile · Profile, status, and tweet page handlers.
src/routes/status.nim - Search · Search endpoints and query routing.
src/routes/search.nim - Media · Media-related endpoints and proxying flows.
src/routes/media.nim - RSS · RSS feed endpoints.
src/routes/rss.nim - Preferences · Preference endpoints and form handling.
src/routes/preferences.nim
Twitter backend
Outbound access, auth, parsing, and data models for Twitter/X.
- API client · High-level outbound request orchestration to Twitter/X.
src/api.nim - HTTP pool · Shared HTTP client and connection management.
src/http_pool.nim - Auth · Authentication, session tokens, and request credentials.
src/auth.nim - Query · Query construction and parameter shaping for outbound calls.
src/query.nim - Parser · Transforms Twitter responses into internal structures.
src/parser.nim - Types · Core internal data structures for parsed Twitter content.
src/types.nim - Redis cache · Redis-backed cache and persistent lightweight state.
src/redis_cache.nim
Rendering
View templates and shared rendering helpers.
- Render utils · Shared rendering helpers used by view modules.
src/views/renderutils.nim - Timeline view · Renders timeline and feed pages.
src/views/timeline.nim - Profile view · Renders profile and status pages.
src/views/profile.nim - Tweet view · Renders tweet, thread, quote, and media fragments.
src/views/tweet.nim - Search view · Renders search results and search UI.
src/views/search.nim
Assets & tools
Static client assets, styling sources, tests, and build helpers.
- Public assets · Shipped CSS, JS, fonts, markdown, and manifest files.
public - Sass sources · Stylesheet source tree for themes and component styling.
src/sass - Integration tests · End-to-end tests covering rendered user flows.
tests - Build tools · Helpers for CSS generation, markdown rendering, and session setup.
tools
Connections 35
- 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.