# andervicario/umbra architecture

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

- Interactive diagram: https://gitdiagram.com/andervicario/umbra
- Repository: https://github.com/andervicario/umbra

## Overview

Umbra is an Android encrypted-messaging client whose main workflow is session-aware startup, sign-in or registration, contact selection, and conversation messaging. Its documented scope is HTTPS-backed communication; the sampled runtime also shows WebSocket notifications, encrypted local message/contact storage, scheduled messages, location sharing, and chat backup. Edges are limited to relationships shown in excerpts, SOURCE INDEX references, or the README; unsampled feature internals are represented by their exact enclosing directories.

Main entry points: [`app/src/main/java/com/av19/utils/ApiService.java`](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/ApiService.java) (REST endpoints), [`app/src/main/java/com/av19/ui/ListContacts.java`](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/ListContacts.java) (Contact list), [`app/src/main/java/com/av19/ui/Conversation.java`](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/Conversation.java) (Conversation), [`app/src/main/java/com/av19/utils/BackgroundWebSocketService.java`](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/BackgroundWebSocketService.java) (Message receiver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry and identity"]
  node_startup["Session startup"]
  node_login["Sign in<br/>[LoginMenu.java]"]
  node_register["Registration<br/>[RegisterMenu.java]"]
end

subgraph group_contacts["Contacts and conversations"]
  node_contacts_ui["Contact list<br/>[ListContacts.java]"]
  node_contact_forms["Contact management"]
  node_contact_edit["Edit contact"]
  node_contact_data["Contact collection<br/>[ContactList.java]"]
  node_contact_model["Contact model<br/>[Contact.java]"]
  node_contact_adapter["Contact rows"]
  node_conversation["Conversation<br/>[Conversation.java]"]
  node_message_adapter["Message rows"]
  node_location["Location sharing"]
  node_profile["Profile updates<br/>[ListContacts.java]"]
end

subgraph group_messaging["Messaging transport"]
  node_api["REST endpoints<br/>[ApiService.java]"]
  node_http_client["HTTPS client"]
  node_background["Message receiver"]
  node_websocket["WebSocket client"]
  node_scheduled["Scheduled send"]
  node_message_queue["Message queue<br/>[MessageQueue.java]"]
  node_api_models["API payloads"]
end

subgraph group_state["Local state and tools"]
  node_database[("Encrypted database")]
  node_message_model["Message model<br/>[Message.java]"]
  node_widget["Message widget<br/>[MessageWidget.java]"]
end

node_user(("User"))
node_server{{"Umbra server"}}

node_user -->|"opens app"| node_startup
node_startup -->|"routes session"| node_contacts_ui
node_startup -->|"routes guest"| node_login
node_login -->|"opens registration"| node_register
node_user -->|"authenticates"| node_login
node_login -.->|"submits credentials"| node_api
node_register -.->|"creates account"| node_api
node_contacts_ui -->|"renders contacts"| node_contact_adapter
node_contact_adapter -->|"displays"| node_contact_model
node_contacts_ui -->|"loads contacts"| node_contact_data
node_contact_data -->|"reads contacts"| node_database
node_contact_forms -.->|"adds contact"| node_contact_data
node_contacts_ui -->|"opens editor"| node_contact_edit
node_contacts_ui -->|"opens chat"| node_conversation
node_conversation -->|"renders messages"| node_message_adapter
node_conversation -->|"stores messages"| node_database
node_conversation -->|"sends messages"| node_api
node_conversation -->|"opens location"| node_location
node_location -.->|"selects location"| node_user
node_http_client -->|"configures client"| node_api
node_api -->|"HTTPS requests"| node_server
node_background -->|"fetches messages"| node_api
node_background -->|"connects listener"| node_websocket
node_websocket -->|"push events"| node_server
node_background -->|"stores received"| node_database
node_background -->|"updates widget"| node_widget
node_conversation -->|"schedules send"| node_scheduled
node_scheduled -->|"sends later"| node_api
node_contacts_ui -.->|"updates profile"| node_profile
node_profile -.->|"uploads picture"| node_api
node_api -->|"uses payloads"| node_api_models
node_contact_data -->|"loads messages"| node_message_model
node_message_adapter -->|"displays"| node_message_model
node_message_queue -->|"holds messages"| node_message_model

click node_startup "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/SplashActivity.java"
click node_login "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/LoginMenu.java"
click node_register "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/RegisterMenu.java"
click node_contacts_ui "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/ListContacts.java"
click node_contact_forms "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/AddContactForm.java"
click node_contact_edit "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/EditContactDialogFragment.java"
click node_contact_data "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/models/ContactList.java"
click node_contact_model "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/models/Contact.java"
click node_contact_adapter "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/adapters/ContactsAdapter.java"
click node_conversation "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/Conversation.java"
click node_message_adapter "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/adapters/MessagesAdapter.java"
click node_location "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/AddLocationMenu.java"
click node_api "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/ApiService.java"
click node_http_client "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/RetrofitClient.java"
click node_background "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/BackgroundWebSocketService.java"
click node_websocket "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/WebSocketClient.java"
click node_scheduled "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/MessageSchedulerReceiver.java"
click node_message_queue "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/models/MessageQueue.java"
click node_database "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/DatabaseHelper.java"
click node_message_model "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/models/Message.java"
click node_widget "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/widgets/MessageWidget.java"
click node_api_models "https://github.com/andervicario/umbra/tree/master/app/src/main/java/com/av19/models/api"
click node_profile "https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/ListContacts.java"

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_startup,node_login,node_register,node_user toneBlue
class node_contacts_ui,node_contact_forms,node_contact_edit,node_contact_data,node_contact_model,node_contact_adapter,node_conversation,node_message_adapter,node_location,node_profile toneAmber
class node_api,node_http_client,node_background,node_websocket,node_scheduled,node_message_queue,node_api_models,node_server toneMint
class node_database,node_message_model,node_widget toneRose
```

## Components

### App entry and identity

- [Session startup](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/SplashActivity.java): `app/src/main/java/com/av19/ui/SplashActivity.java`
- [Sign in](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/LoginMenu.java): `app/src/main/java/com/av19/ui/LoginMenu.java`
- [Registration](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/RegisterMenu.java): `app/src/main/java/com/av19/ui/RegisterMenu.java`

### Contacts and conversations

- [Contact list](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/ListContacts.java): `app/src/main/java/com/av19/ui/ListContacts.java`
- [Contact management](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/AddContactForm.java): `app/src/main/java/com/av19/ui/AddContactForm.java`
- [Edit contact](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/EditContactDialogFragment.java): `app/src/main/java/com/av19/ui/EditContactDialogFragment.java`
- [Contact collection](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/models/ContactList.java): `app/src/main/java/com/av19/models/ContactList.java`
- [Contact model](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/models/Contact.java): `app/src/main/java/com/av19/models/Contact.java`
- [Contact rows](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/adapters/ContactsAdapter.java): `app/src/main/java/com/av19/adapters/ContactsAdapter.java`
- [Conversation](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/Conversation.java): `app/src/main/java/com/av19/ui/Conversation.java`
- [Message rows](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/adapters/MessagesAdapter.java): `app/src/main/java/com/av19/adapters/MessagesAdapter.java`
- [Location sharing](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/AddLocationMenu.java): `app/src/main/java/com/av19/ui/AddLocationMenu.java`
- [Profile updates](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/ui/ListContacts.java): `app/src/main/java/com/av19/ui/ListContacts.java`

### Messaging transport

- [REST endpoints](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/ApiService.java): `app/src/main/java/com/av19/utils/ApiService.java`
- [HTTPS client](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/RetrofitClient.java): `app/src/main/java/com/av19/utils/RetrofitClient.java`
- [Message receiver](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/BackgroundWebSocketService.java): `app/src/main/java/com/av19/utils/BackgroundWebSocketService.java`
- [WebSocket client](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/WebSocketClient.java): `app/src/main/java/com/av19/utils/WebSocketClient.java`
- [Scheduled send](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/MessageSchedulerReceiver.java): `app/src/main/java/com/av19/utils/MessageSchedulerReceiver.java`
- [Message queue](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/models/MessageQueue.java): `app/src/main/java/com/av19/models/MessageQueue.java`
- [API payloads](https://github.com/andervicario/umbra/tree/master/app/src/main/java/com/av19/models/api): `app/src/main/java/com/av19/models/api`

### Local state and tools

- [Encrypted database](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/utils/DatabaseHelper.java): `app/src/main/java/com/av19/utils/DatabaseHelper.java`
- [Message model](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/models/Message.java): `app/src/main/java/com/av19/models/Message.java`
- [Message widget](https://github.com/andervicario/umbra/blob/master/app/src/main/java/com/av19/widgets/MessageWidget.java): `app/src/main/java/com/av19/widgets/MessageWidget.java`

### Other components

- **User**
- **Umbra server**

## Connections

- User → Session startup: opens app (evidence: `app/src/main/java/com/av19/ui/SplashActivity.java`)
- Session startup → Contact list: routes session (evidence: `app/src/main/java/com/av19/ui/SplashActivity.java`)
- Session startup → Sign in: routes guest (evidence: `app/src/main/java/com/av19/ui/SplashActivity.java`)
- Sign in → Registration: opens registration (evidence: `app/src/main/java/com/av19/ui/LoginMenu.java`)
- User → Sign in: authenticates (evidence: `README.md`)
- Sign in → REST endpoints: submits credentials (evidence: `app/src/main/java/com/av19/ui/LoginMenu.java`)
- Registration → REST endpoints: creates account (evidence: `app/src/main/java/com/av19/ui/RegisterMenu.java`)
- Contact list → Contact rows: renders contacts (evidence: `app/src/main/java/com/av19/ui/ListContacts.java`)
- Contact rows → Contact model: displays (evidence: `app/src/main/java/com/av19/adapters/ContactsAdapter.java`)
- Contact list → Contact collection: loads contacts (evidence: `app/src/main/java/com/av19/ui/ListContacts.java`)
- Contact collection → Encrypted database: reads contacts (evidence: `app/src/main/java/com/av19/models/ContactList.java`)
- Contact management → Contact collection: adds contact
- Contact list → Edit contact: opens editor (evidence: `app/src/main/java/com/av19/ui/ListContacts.java`)
- Contact list → Conversation: opens chat
- Conversation → Message rows: renders messages (evidence: `app/src/main/java/com/av19/ui/Conversation.java`)
- Conversation → Encrypted database: stores messages (evidence: `app/src/main/java/com/av19/ui/Conversation.java`)
- Conversation → REST endpoints: sends messages (evidence: `app/src/main/java/com/av19/ui/Conversation.java`)
- Conversation → Location sharing: opens location (evidence: `app/src/main/java/com/av19/ui/Conversation.java`)
- Location sharing → User: selects location
- HTTPS client → REST endpoints: configures client (evidence: `app/src/main/java/com/av19/utils/RetrofitClient.java`)
- REST endpoints → Umbra server: HTTPS requests (evidence: `README.md`)
- Message receiver → REST endpoints: fetches messages (evidence: `app/src/main/java/com/av19/utils/BackgroundWebSocketService.java`)
- Message receiver → WebSocket client: connects listener (evidence: `app/src/main/java/com/av19/utils/BackgroundWebSocketService.java`)
- WebSocket client → Umbra server: push events (evidence: `app/src/main/java/com/av19/utils/WebSocketClient.java`)
- Message receiver → Encrypted database: stores received (evidence: `app/src/main/java/com/av19/utils/BackgroundWebSocketService.java`)
- Message receiver → Message widget: updates widget (evidence: `app/src/main/java/com/av19/utils/BackgroundWebSocketService.java`)
- Conversation → Scheduled send: schedules send (evidence: `app/src/main/java/com/av19/ui/Conversation.java`)
- Scheduled send → REST endpoints: sends later (evidence: `app/src/main/java/com/av19/utils/MessageSchedulerReceiver.java`)
- Contact list → Profile updates: updates profile (evidence: `app/src/main/java/com/av19/ui/ListContacts.java`)
- Profile updates → REST endpoints: uploads picture (evidence: `app/src/main/java/com/av19/ui/ListContacts.java`)
- REST endpoints → API payloads: uses payloads (evidence: `app/src/main/java/com/av19/utils/ApiService.java`)
- Contact collection → Message model: loads messages (evidence: `app/src/main/java/com/av19/models/ContactList.java`)
- Message rows → Message model: displays (evidence: `app/src/main/java/com/av19/adapters/MessagesAdapter.java`)
- Message queue → Message model: holds messages (evidence: `app/src/main/java/com/av19/models/MessageQueue.java`)
