# joker20380/family_connect architecture

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

- Interactive diagram: https://gitdiagram.com/joker20380/family_connect
- Repository: https://github.com/joker20380/family_connect

## Overview

Family Connect is a multi-platform private-connectivity client with device activation, regional encrypted gateway connections, and a separate messenger. The main workflow is invitation activation, choosing a gateway/transport, and managing a VPN session; Android also runs control synchronization and recovery. Messaging is a distinct branch, not a consequence of connecting the VPN. The README documents Linux and Windows clients and pilot server capabilities; sampled implementation details are limited, so uncertain component wiring is omitted.

Main entry points: [`clients/android/app/src/main/java/com/familyconnect/app/ConnectionService.java`](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ConnectionService.java) (Connection service), [`clients/android/app/src/main/java/com/familyconnect/app/MainActivity.java`](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/MainActivity.java) (Android app), [`clients/android/app/src/main/java/com/familyconnect/app/ControlTransaction.java`](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ControlTransaction.java) (Control transactions), [`clients/android/app/src/main/java/com/familyconnect/app/ChatRuntime.java`](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ChatRuntime.java) (Chat runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client applications"]
  node_invitation["Invitation activation"]
  node_android["Android app<br/>[MainActivity.java]"]
  node_desktop["Linux / Windows apps<br/>[app.py]"]
end

subgraph group_connection["Gateway connection"]
  node_connection_service["Connection service"]
  node_selection["Transport selection<br/>[Transport.java]"]
  node_profiles[("Connection profiles<br/>[ProfileStore.java]")]
  node_awg["AWG tunnel<br/>[TunnelEngine.java]"]
  node_tcp["TCP tunnel"]
end

subgraph group_control["Device control"]
  node_control_flow["Control operations"]
  node_control_transaction["Control transactions"]
  node_identity_vault[("Device identity vault")]
  node_journal[("Durable control journal")]
end

subgraph group_messaging["Messaging"]
  node_chat_ui["Messenger UI<br/>[ChatActivity.java]"]
  node_chat_runtime["Chat runtime<br/>[ChatRuntime.java]"]
  node_chat_store[("Encrypted chat store")]
  node_chat_delivery["Background delivery"]
end

subgraph group_services["Backend services"]
  node_gateways["Regional gateways<br/>[gateways.py]"]
  node_control_api["Control API<br/>[api.py]"]
  node_provisioning["Provisioning<br/>[application.py]"]
  node_messenger_relay["Messenger relay<br/>[server.py]"]
end

node_family(("Family member"))
node_internet(("Internet access"))

node_family -->|"uses"| node_android
node_family -->|"uses"| node_desktop
node_android -->|"activates from invitation"| node_invitation
node_invitation -->|"requests access"| node_control_api
node_control_api -->|"provisions device"| node_provisioning
node_android -->|"starts connection"| node_connection_service
node_connection_service -->|"runs control startup"| node_control_flow
node_connection_service -->|"selects transport"| node_selection
node_connection_service -->|"checks profiles"| node_profiles
node_connection_service -->|"starts tunnel"| node_awg
node_connection_service -->|"starts tunnel"| node_tcp
node_connection_service -->|"connects to selected gateway"| node_gateways
node_control_flow -->|"coordinates operations"| node_control_transaction
node_control_transaction -->|"loads identity"| node_identity_vault
node_control_transaction -->|"persists state"| node_journal
node_control_transaction -->|"sends control requests"| node_control_api
node_android -->|"opens messenger"| node_chat_ui
node_chat_ui -->|"uses"| node_chat_runtime
node_chat_runtime -->|"stores encrypted messages"| node_chat_store
node_chat_runtime -->|"runs delivery"| node_chat_delivery
node_chat_delivery -->|"exchanges messages"| node_messenger_relay
node_gateways -->|"provides access"| node_internet

click node_invitation "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ControlEnrollment.java"
click node_android "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/MainActivity.java"
click node_desktop "https://github.com/joker20380/family_connect/blob/main/clients/desktop/app.py"
click node_connection_service "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ConnectionService.java"
click node_selection "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/Transport.java"
click node_profiles "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ProfileStore.java"
click node_awg "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/TunnelEngine.java"
click node_tcp "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/TcpTunnelEngine.java"
click node_gateways "https://github.com/joker20380/family_connect/blob/main/control/product/gateways.py"
click node_control_flow "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ControlOperations.java"
click node_control_transaction "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ControlTransaction.java"
click node_identity_vault "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ControlIdentityVault.java"
click node_journal "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ControlJournal.java"
click node_control_api "https://github.com/joker20380/family_connect/blob/main/control/product/api.py"
click node_provisioning "https://github.com/joker20380/family_connect/blob/main/provisioning/application.py"
click node_chat_ui "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ChatActivity.java"
click node_chat_runtime "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ChatRuntime.java"
click node_chat_store "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ChatStoreCipher.java"
click node_chat_delivery "https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ChatDeliveryService.java"
click node_messenger_relay "https://github.com/joker20380/family_connect/blob/main/messenger/server.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_invitation,node_android,node_desktop toneBlue
class node_connection_service,node_selection,node_profiles,node_awg,node_tcp toneAmber
class node_control_flow,node_control_transaction,node_identity_vault,node_journal toneMint
class node_chat_ui,node_chat_runtime,node_chat_store,node_chat_delivery toneRose
class node_gateways,node_control_api,node_provisioning,node_messenger_relay,node_family,node_internet toneIndigo
```

## Components

### Client applications

- [Invitation activation](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ControlEnrollment.java): `clients/android/app/src/main/java/com/familyconnect/app/ControlEnrollment.java`
- [Android app](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/MainActivity.java): `clients/android/app/src/main/java/com/familyconnect/app/MainActivity.java`
- [Linux / Windows apps](https://github.com/joker20380/family_connect/blob/main/clients/desktop/app.py): `clients/desktop/app.py`

### Gateway connection

- [Connection service](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ConnectionService.java): `clients/android/app/src/main/java/com/familyconnect/app/ConnectionService.java`
- [Transport selection](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/Transport.java): `clients/android/app/src/main/java/com/familyconnect/app/Transport.java`
- [Connection profiles](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ProfileStore.java): `clients/android/app/src/main/java/com/familyconnect/app/ProfileStore.java`
- [AWG tunnel](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/TunnelEngine.java): `clients/android/app/src/main/java/com/familyconnect/app/TunnelEngine.java`
- [TCP tunnel](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/TcpTunnelEngine.java): `clients/android/app/src/main/java/com/familyconnect/app/TcpTunnelEngine.java`

### Device control

- [Control operations](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ControlOperations.java): `clients/android/app/src/main/java/com/familyconnect/app/ControlOperations.java`
- [Control transactions](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ControlTransaction.java): `clients/android/app/src/main/java/com/familyconnect/app/ControlTransaction.java`
- [Device identity vault](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ControlIdentityVault.java): `clients/android/app/src/main/java/com/familyconnect/app/ControlIdentityVault.java`
- [Durable control journal](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ControlJournal.java): `clients/android/app/src/main/java/com/familyconnect/app/ControlJournal.java`

### Messaging

- [Messenger UI](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ChatActivity.java): `clients/android/app/src/main/java/com/familyconnect/app/ChatActivity.java`
- [Chat runtime](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ChatRuntime.java): `clients/android/app/src/main/java/com/familyconnect/app/ChatRuntime.java`
- [Encrypted chat store](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ChatStoreCipher.java): `clients/android/app/src/main/java/com/familyconnect/app/ChatStoreCipher.java`
- [Background delivery](https://github.com/joker20380/family_connect/blob/main/clients/android/app/src/main/java/com/familyconnect/app/ChatDeliveryService.java): `clients/android/app/src/main/java/com/familyconnect/app/ChatDeliveryService.java`

### Backend services

- [Regional gateways](https://github.com/joker20380/family_connect/blob/main/control/product/gateways.py): `control/product/gateways.py`
- [Control API](https://github.com/joker20380/family_connect/blob/main/control/product/api.py): `control/product/api.py`
- [Provisioning](https://github.com/joker20380/family_connect/blob/main/provisioning/application.py): `provisioning/application.py`
- [Messenger relay](https://github.com/joker20380/family_connect/blob/main/messenger/server.py): `messenger/server.py`

### Other components

- **Family member**
- **Internet access**

## Connections

- Family member → Android app: uses
- Family member → Linux / Windows apps: uses
- Android app → Invitation activation: activates from invitation
- Invitation activation → Control API: requests access
- Control API → Provisioning: provisions device
- Android app → Connection service: starts connection
- Connection service → Control operations: runs control startup
- Connection service → Transport selection: selects transport
- Connection service → Connection profiles: checks profiles
- Connection service → AWG tunnel: starts tunnel
- Connection service → TCP tunnel: starts tunnel
- Connection service → Regional gateways: connects to selected gateway
- Control operations → Control transactions: coordinates operations
- Control transactions → Device identity vault: loads identity
- Control transactions → Durable control journal: persists state
- Control transactions → Control API: sends control requests
- Android app → Messenger UI: opens messenger
- Messenger UI → Chat runtime: uses
- Chat runtime → Encrypted chat store: stores encrypted messages
- Chat runtime → Background delivery: runs delivery
- Background delivery → Messenger relay: exchanges messages
- Regional gateways → Internet access: provides access