# ferdium/ferdium-app architecture

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

- Interactive diagram: https://gitdiagram.com/ferdium/ferdium-app
- Repository: https://github.com/ferdium/ferdium-app

## Overview

#### 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: [`src/components`](https://github.com/ferdium/ferdium-app/tree/develop/src/components) (Application UI), [`src/electron`](https://github.com/ferdium/ferdium-app/tree/develop/src/electron) (Electron integration), [`src/stores`](https://github.com/ferdium/ferdium-app/tree/develop/src/stores) (Client state), [`src/api`](https://github.com/ferdium/ferdium-app/tree/develop/src/api) (Client API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop client"]
  node_entry["Application entry<br/>[index.ts]"]
  node_ui["Application UI<br/>React renderer"]
  node_state["Client state<br/>Stores and actions"]
  node_api["Client API<br/>API boundary"]
  node_electron["Electron integration<br/>OS and IPC integration"]
  node_webview["Service webviews<br/>Embedded service runtime"]
  node_features{{"Product features<br/>Feature extensions"}}
end

subgraph group_server["Local server"]
  node_server_runtime[("Internal server<br/>HTTP and domain runtime")]
end

subgraph group_external["External boundaries"]
  node_user(("End user<br/>External actor"))
  node_websites(("Remote services<br/>External websites"))
  node_os(("Host operating system<br/>External system"))
  node_account(("Ferdium-compatible server<br/>Optional external server"))
  node_dbus(("D-Bus clients<br/>External integration"))
end

node_user -->|"interacts with"| node_ui
node_ui -->|"uses"| node_state
node_state -->|"coordinates through"| node_api
node_state -->|"updates"| node_ui
node_ui -->|"hosts"| node_webview
node_webview -->|"loads"| node_websites
node_ui -->|"uses IPC"| node_electron
node_electron -->|"integrates with"| node_os
node_electron -->|"controls"| node_server_runtime
node_api -->|"represents boundary to"| node_server_runtime
node_api -->|"supports"| node_account
node_features -->|"extends"| node_ui
node_dbus -.->|"integrates through"| node_electron

click node_entry "https://github.com/ferdium/ferdium-app/blob/develop/src/index.ts"
click node_ui "https://github.com/ferdium/ferdium-app/tree/develop/src/components"
click node_state "https://github.com/ferdium/ferdium-app/tree/develop/src/stores"
click node_api "https://github.com/ferdium/ferdium-app/tree/develop/src/api"
click node_electron "https://github.com/ferdium/ferdium-app/tree/develop/src/electron"
click node_webview "https://github.com/ferdium/ferdium-app/tree/develop/src/webview"
click node_features "https://github.com/ferdium/ferdium-app/tree/develop/src/features"
click node_server_runtime "https://github.com/ferdium/ferdium-app/tree/develop/src/internal-server"

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_entry,node_ui,node_state,node_api,node_electron,node_webview,node_features toneBlue
class node_server_runtime toneAmber
class node_user,node_websites,node_os,node_account,node_dbus toneMint
```

## Components

### Desktop client

Electron renderer, host integration, and embedded service runtime.

- [Application entry](https://github.com/ferdium/ferdium-app/blob/develop/src/index.ts): Electron application entry · `src/index.ts`
- [Application UI](https://github.com/ferdium/ferdium-app/tree/develop/src/components): React renderer · Screens and reusable controls compose the desktop workspace. · `src/components`
- [Client state](https://github.com/ferdium/ferdium-app/tree/develop/src/stores): Stores and actions · Persistent-session-facing state and application operations. · `src/stores`
- [Client API](https://github.com/ferdium/ferdium-app/tree/develop/src/api): API boundary · Client abstractions for application, service, recipe, feature, and server operations. · `src/api`
- [Electron integration](https://github.com/ferdium/ferdium-app/tree/develop/src/electron): OS and IPC integration · Windows, settings, permissions, IPC, updates, tray, and local-server control. · `src/electron`
- [Service webviews](https://github.com/ferdium/ferdium-app/tree/develop/src/webview): Embedded service runtime · Applies browser behavior to embedded service views. · `src/webview`
- [Product features](https://github.com/ferdium/ferdium-app/tree/develop/src/features): Feature extensions · Optional Workspaces, Todos, quick switching, recipes, and related extensions. · `src/features`

### Local server

Separate HTTP and durable domain-data runtime.

- [Internal server](https://github.com/ferdium/ferdium-app/tree/develop/src/internal-server): HTTP and domain runtime · Owns controllers, domain entities, migrations, and SQLite-backed state. · `src/internal-server`

### External boundaries

Users, operating-system facilities, remote services, and integrations.

- **End user**: External actor
- **Remote services**: External websites · Messaging and productivity websites loaded in service webviews.
- **Host operating system**: External system
- **Ferdium-compatible server**: Optional external server
- **D-Bus clients**: External integration

## Connections

- 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
