# sparklost/endcord architecture

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

- Interactive diagram: https://gitdiagram.com/sparklost/endcord
- Repository: https://github.com/sparklost/endcord

## Overview

Endcord is a terminal-first Discord client, with an optional GTK-backed window. Its principal workflow is selecting or creating an account, connecting to Discord, then browsing channels and messages and issuing commands through the interactive client. The map preserves major documented branches such as search, media, voice, and presence. The source excerpts are partial, so some subsystem links rely on documented product behavior and are omitted where ownership is unclear.

Main entry points: [`endcord/app.py`](https://github.com/sparklost/endcord/blob/main/endcord/app.py) (Client orchestration), [`main.py`](https://github.com/sparklost/endcord/blob/main/main.py) (Application entry), [`endcord/profile_manager.py`](https://github.com/sparklost/endcord/blob/main/endcord/profile_manager.py) (Profile manager), [`endcord/auth.py`](https://github.com/sparklost/endcord/blob/main/endcord/auth.py) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Startup and accounts"]
  node_main["Application entry<br/>[main.py]"]
  node_profiles["Profile manager<br/>[profile_manager.py]"]
end

subgraph group_discord["Discord connectivity"]
  node_auth["Authentication<br/>[auth.py]"]
  node_discord_api["Discord API client<br/>[discord.py]"]
  node_gateway["Gateway connection<br/>[gateway.py]"]
end

subgraph group_interaction["Client interaction"]
  node_app["Client orchestration<br/>[app.py]"]
  node_tui["Terminal interface<br/>[tui.py]"]
  node_gtk["GTK interface<br/>[gtkcurses.py]"]
  node_parser["Commands and parsing<br/>[parser.py]"]
  node_search["Search and assist<br/>[search.py]"]
end

subgraph group_content["Content and media"]
  node_formatter["Message formatting<br/>[formatter.py]"]
  node_message["Message operations<br/>[message.py]"]
  node_media["Media handling<br/>[media.py]"]
  node_voice["Voice calls<br/>[voice.py]"]
  node_rpc["Presence and RPC<br/>[rpc.py]"]
end

subgraph group_local["Local services"]
  node_config["Configuration<br/>[config.py]"]
  node_peripherals["Desktop services<br/>[peripherals.py]"]
  node_cache[("Channel chat cache<br/>[app.py]")]
end

node_user(("User"))
node_discord_service(("Discord"))
node_external_media(("Media applications"))

node_user -->|"starts client"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"starts account flow"| node_profiles
node_profiles -->|"authenticates"| node_auth
node_auth -->|"sends login requests"| node_discord_service
node_profiles -->|"opens client"| node_app
node_app -->|"requests Discord data"| node_discord_api
node_app -->|"handles live events"| node_gateway
node_discord_api -->|"sends API requests"| node_discord_service
node_gateway -->|"exchanges events"| node_discord_service
node_user -->|"interacts"| node_tui
node_app -->|"updates interface"| node_tui
node_app -.->|"supports windowed UI"| node_gtk
node_app -->|"dispatches commands"| node_parser
node_app -->|"requests suggestions"| node_search
node_app -->|"formats chat"| node_formatter
node_app -->|"performs message actions"| node_message
node_app -->|"reads and writes chat"| node_cache
node_app -->|"handles attachments"| node_media
node_media -.->|"opens media"| node_external_media
node_app -->|"supports voice calls"| node_voice
node_app -->|"updates presence"| node_rpc
node_app -->|"uses desktop services"| node_peripherals

click node_main "https://github.com/sparklost/endcord/blob/main/main.py"
click node_profiles "https://github.com/sparklost/endcord/blob/main/endcord/profile_manager.py"
click node_auth "https://github.com/sparklost/endcord/blob/main/endcord/auth.py"
click node_discord_api "https://github.com/sparklost/endcord/blob/main/endcord/discord.py"
click node_gateway "https://github.com/sparklost/endcord/blob/main/endcord/gateway.py"
click node_app "https://github.com/sparklost/endcord/blob/main/endcord/app.py"
click node_tui "https://github.com/sparklost/endcord/blob/main/endcord/tui.py"
click node_gtk "https://github.com/sparklost/endcord/blob/main/endcord/gtkcurses.py"
click node_parser "https://github.com/sparklost/endcord/blob/main/endcord/parser.py"
click node_search "https://github.com/sparklost/endcord/blob/main/endcord/search.py"
click node_formatter "https://github.com/sparklost/endcord/blob/main/endcord/formatter.py"
click node_message "https://github.com/sparklost/endcord/blob/main/endcord/message.py"
click node_media "https://github.com/sparklost/endcord/blob/main/endcord/media.py"
click node_voice "https://github.com/sparklost/endcord/blob/main/endcord/voice.py"
click node_rpc "https://github.com/sparklost/endcord/blob/main/endcord/rpc.py"
click node_config "https://github.com/sparklost/endcord/blob/main/endcord/config.py"
click node_peripherals "https://github.com/sparklost/endcord/blob/main/endcord/peripherals.py"
click node_cache "https://github.com/sparklost/endcord/blob/main/endcord/app.py"

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_main,node_profiles,node_user toneBlue
class node_auth,node_discord_api,node_gateway toneAmber
class node_app,node_tui,node_gtk,node_parser,node_search toneMint
class node_formatter,node_message,node_media,node_voice,node_rpc toneRose
class node_config,node_peripherals,node_cache,node_discord_service,node_external_media toneIndigo
```

## Components

### Startup and accounts

- [Application entry](https://github.com/sparklost/endcord/blob/main/main.py): `main.py`
- [Profile manager](https://github.com/sparklost/endcord/blob/main/endcord/profile_manager.py): `endcord/profile_manager.py`

### Discord connectivity

- [Authentication](https://github.com/sparklost/endcord/blob/main/endcord/auth.py): `endcord/auth.py`
- [Discord API client](https://github.com/sparklost/endcord/blob/main/endcord/discord.py): `endcord/discord.py`
- [Gateway connection](https://github.com/sparklost/endcord/blob/main/endcord/gateway.py): `endcord/gateway.py`

### Client interaction

- [Client orchestration](https://github.com/sparklost/endcord/blob/main/endcord/app.py): `endcord/app.py`
- [Terminal interface](https://github.com/sparklost/endcord/blob/main/endcord/tui.py): `endcord/tui.py`
- [GTK interface](https://github.com/sparklost/endcord/blob/main/endcord/gtkcurses.py): `endcord/gtkcurses.py`
- [Commands and parsing](https://github.com/sparklost/endcord/blob/main/endcord/parser.py): `endcord/parser.py`
- [Search and assist](https://github.com/sparklost/endcord/blob/main/endcord/search.py): `endcord/search.py`

### Content and media

- [Message formatting](https://github.com/sparklost/endcord/blob/main/endcord/formatter.py): `endcord/formatter.py`
- [Message operations](https://github.com/sparklost/endcord/blob/main/endcord/message.py): `endcord/message.py`
- [Media handling](https://github.com/sparklost/endcord/blob/main/endcord/media.py): `endcord/media.py`
- [Voice calls](https://github.com/sparklost/endcord/blob/main/endcord/voice.py): `endcord/voice.py`
- [Presence and RPC](https://github.com/sparklost/endcord/blob/main/endcord/rpc.py): `endcord/rpc.py`

### Local services

- [Configuration](https://github.com/sparklost/endcord/blob/main/endcord/config.py): `endcord/config.py`
- [Desktop services](https://github.com/sparklost/endcord/blob/main/endcord/peripherals.py): `endcord/peripherals.py`
- [Channel chat cache](https://github.com/sparklost/endcord/blob/main/endcord/app.py): `endcord/app.py`

### Other components

- **User**
- **Discord**
- **Media applications**

## Connections

- User → Application entry: starts client
- Application entry → Configuration: loads settings
- Application entry → Profile manager: starts account flow
- Profile manager → Authentication: authenticates
- Authentication → Discord: sends login requests
- Profile manager → Client orchestration: opens client
- Client orchestration → Discord API client: requests Discord data
- Client orchestration → Gateway connection: handles live events
- Discord API client → Discord: sends API requests
- Gateway connection → Discord: exchanges events
- User → Terminal interface: interacts
- Client orchestration → Terminal interface: updates interface
- Client orchestration → GTK interface: supports windowed UI
- Client orchestration → Commands and parsing: dispatches commands
- Client orchestration → Search and assist: requests suggestions
- Client orchestration → Message formatting: formats chat
- Client orchestration → Message operations: performs message actions
- Client orchestration → Channel chat cache: reads and writes chat
- Client orchestration → Media handling: handles attachments
- Media handling → Media applications: opens media
- Client orchestration → Voice calls: supports voice calls
- Client orchestration → Presence and RPC: updates presence
- Client orchestration → Desktop services: uses desktop services