How ferdium/ferdium-app works
Overview
Ferdium is a cross-platform Electron desktop application that combines multiple messaging and productivity services into one workspace. The README documents Franz-account compatibility, service organization, Workspaces, Todos, custom CSS, and downloadable desktop releases.
Entry points and boundaries
• src/index.ts is the main TypeScript application entry visible in the source tree.
• src/app.tsx is the renderer-side application root.
• src/internal-server/start.ts marks a separate local-server runtime with HTTP controllers, models, migrations, and SQLite state.
• docs/DBUS.md and docs/INTERNAL_SERVER.md document external integration boundaries, but source contents are not supplied here.
Core components
• Application UI and screens — src/components: React presentation for authentication, service views, settings, downloads, navigation, and reusable controls. src/containers provides screen/window-level composition around these views.
• Client state and commands — src/stores: persistent-session-facing application state for users, services, recipes, settings, requests, features, and UI state. src/actions groups user and application operations that update or coordinate this state.
• API boundary — src/api: client API abstractions for application, user, service, recipe, feature, and local-server operations, including server-specific implementations under src/api/server.
• Electron and operating-system integration — src/electron: settings, windows, deep links, exceptions, permissions, and IPC handlers for clipboard, downloads, updates, tray behavior, session storage, and local-server control.
• Embedded service runtime — src/webview: behavior applied to service webviews, including authentication/session handling, context menus, notifications, dark mode, language detection, screen sharing, zoom, and window-opening policies.
• Optional product features — src/features: extension-style areas such as Workspaces, Todos, quick switching, service proxying, community recipes, web controls, basic authentication, and debug-info publishing. Feature-specific stores, actions, screens, and preload code are kept with each feature.
• Local server and durable domain data — src/internal-server: HTTP controllers, authentication-related models, User/Service/Recipe/Workspace entities, database configuration, migrations, and a SQLite template. This is a separate ownership boundary from the renderer and Electron host.
Relationships
The desktop user interacts with the React UI, which is organized around stores, actions, and API abstractions. Service screens host embedded webviews; the webview layer owns service-specific browser behavior rather than the remote services themselves. Electron IPC connects renderer concerns to OS facilities and local-server functions. The local server owns domain persistence and HTTP endpoints, while the client API layer represents that boundary. Feature directories extend the application through their own state and UI rather than forming a single sequential pipeline.
External actors and state
External actors include the end user, remote messaging/productivity websites loaded in webviews, an optional Ferdium-compatible account/server, the host operating system, and documented D-Bus clients. User configuration is documented under platform-specific user-data locations; the README specifically identifies USER_DATA/Ferdium/config/custom.css as a customization surface.
Main entry points: components Application UI · electron Electron integration · stores Client state · api Client API
Components 13
Desktop client
Electron renderer, host integration, and embedded service runtime.
- Application entry
src/index.ts - Application UI · Screens and reusable controls compose the desktop workspace.
src/components - Client state · Persistent-session-facing state and application operations.
src/stores - Client API · Client abstractions for application, service, recipe, feature, and server operations.
src/api - Electron integration · Windows, settings, permissions, IPC, updates, tray, and local-server control.
src/electron - Service webviews · Applies browser behavior to embedded service views.
src/webview - Product features · Optional Workspaces, Todos, quick switching, recipes, and related extensions.
src/features
Local server
Separate HTTP and durable domain-data runtime.
- Internal server · Owns controllers, domain entities, migrations, and SQLite-backed state.
src/internal-server
External boundaries
Users, operating-system facilities, remote services, and integrations.
- End user
- Remote services · Messaging and productivity websites loaded in service webviews.
- Host operating system
- Ferdium-compatible server
- D-Bus clients
Connections 13
- End user → Application UI: interacts with
- Application UI → Client state: uses
- Client state → Client API: coordinates through
- Client state → Application UI: updates
- Application UI → Service webviews: hosts
- Service webviews → Remote services: loads
- Application UI → Electron integration: uses IPC
- Electron integration → Host operating system: integrates with
- Electron integration → Internal server: controls
- Client API → Internal server: represents boundary to
- Client API → Ferdium-compatible server: supports
- Product features → Application UI: extends
- D-Bus clients → Electron integration: integrates through