Architecture & Design

fedtail is engineered for people who value conversation context, non-jumping chronological timelines, and complete discussion threads.

Foundational Principles

1. Nothing jumps. Opening a lane places you at the first unread post. New arrivals never push what you are currently reading. You consume feeds in order, just like RSS.
2. Every reply knows its parent. A quote strip above each response shows the origin post; a single click expands the entire tree.
3. Lanes are segregated. People, bots, direct replies, and mentions are cleanly partitioned into distinct feeds.
4. Private by default. New posts target followers only. Replies never exceed the visibility level of the parent note.
5. Config-driven. Every behavior is governed by explicit settings in config.toml rather than GUI preference dialogs.
6. No client tokens sent to third-party instances. Missing thread data fetched via ActivityPub is retrieved anonymously without leaking user tokens.
7. Headless core. The application engine is fully decoupled from presentation. Frontends (Qt, TUI, Web) interact via events and futures.
8. One profile per account. Profiles remain isolated; multiple profiles can be switched easily or merged into a single window.
9. No patronizing moderation (arts mode). In tribute to @arts (founder of Point.im), content is presented as-is with full user agency.

Architectural Components

• Core Engine (fedtail/core): Headless orchestration of networking, storage, polling, and event dispatch.
• Data Persistence: Local SQLite database storing cached status entities, thread graph relationships, read markers, and subscriptions.
• Thread Reassembly: Fetches missing conversational branches directly from origin author instances when home servers lack federated context.
• Frontends (fedtail/frontends):
  • qt: Native desktop UI built on PySide6.
  • tui: Terminal text-mode interface.
  • web: Embedded lightweight browser interface.
  • cli: Scriptable terminal commands (fedtail tail, fedtail show, etc.).