# xiang20041021/liumarat architecture

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

- Interactive diagram: https://gitdiagram.com/xiang20041021/liumarat
- Repository: https://github.com/xiang20041021/liumarat

## Overview

LIUMA is an Android device-management agent paired with a web dashboard and Fastify backend. The main flow starts when the Android app launches its persistent service, connects to the backend, and receives commands; users operate the dashboard through the backend’s APIs and device socket channel. The repository also includes authentication, device enrollment and records, logs, settings, and a broad set of device capabilities. The README is empty, and many feature and route implementations were not excerpted, so those subsystems are represented at directory level and unsupported links are omitted.

Main entry points: [`LIUMA/app/src/main/java/com/liuma/app/service/MainService.java`](https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/service/MainService.java) (Persistent service), [`LIUMA/app/src/main/java/com/liuma/app/core/network/SocketClient.java`](https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/core/network/SocketClient.java) (Device socket client), [`backend/src/services/socket.ts`](https://github.com/xiang20041021/liumarat/blob/main/backend/src/services/socket.ts) (Device socket service), [`backend/src/db/index.ts`](https://github.com/xiang20041021/liumarat/blob/main/backend/src/db/index.ts) (Database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web console"]
  node_webapp["Dashboard pages"]
  node_websocket["Web socket client<br/>[socket.ts]"]
  node_webapi["Web API client<br/>[api.ts]"]
end

subgraph group_server["Backend service"]
  node_serverentry["HTTP server<br/>[index.ts]"]
  node_authroutes["Authentication routes<br/>[auth.ts]"]
  node_routes["Product routes"]
  node_authmw["Auth middleware<br/>[auth.ts]"]
  node_socketserver["Device socket service<br/>[socket.ts]"]
  node_tasks["Task service<br/>[tasks.ts]"]
  node_dbapi["Database access<br/>[index.ts]"]
  node_schema[("Persistent records<br/>[schema.ts]")]
  node_userdb[("User and device data<br/>[schema.ts]")]
end

subgraph group_agent["Android agent"]
  node_androidapp["Android startup<br/>[LiumaApp.java]"]
  node_mainservice["Persistent service<br/>[MainService.java]"]
  node_socketclient["Device socket client<br/>[SocketClient.java]"]
  node_commandrouter["Command router"]
  node_protocol["Wire protocol<br/>[Protocol.java]"]
  node_permissions["Permission manager"]
end

subgraph group_device["Device capabilities"]
  node_devicefeatures["Device feature handlers"]
  node_gps["Location tracking"]
  node_screen["Screen and remote control"]
  node_hvnc["Remote display service"]
  node_storage["Files and transfers"]
end

node_operator(("Dashboard user"))

node_operator -->|"uses"| node_webapp
node_androidapp -->|"starts"| node_mainservice
node_mainservice -->|"initializes"| node_commandrouter
node_mainservice -->|"starts clipboard and GPS"| node_devicefeatures
node_socketclient -->|"initializes"| node_commandrouter
node_socketclient -->|"uses constants"| node_protocol
node_mainservice -->|"uses socket"| node_socketclient
node_mainservice -->|"uses constants"| node_protocol
node_devicefeatures -.->|"checks access"| node_permissions
node_serverentry -->|"registers"| node_authroutes
node_serverentry -->|"registers"| node_routes
node_serverentry -->|"registers"| node_socketserver
node_authroutes -->|"reads and writes"| node_dbapi
node_authroutes -->|"uses session helpers"| node_authmw
node_authmw -->|"checks sessions"| node_dbapi
node_socketserver -->|"reads and writes"| node_dbapi
node_tasks -->|"uses socket service"| node_socketserver
node_dbapi -->|"queries records"| node_schema
node_webapp -.->|"calls API"| node_webapi
node_webapp -.->|"uses device channel"| node_websocket
node_socketclient -.->|"exchanges device events"| node_socketserver
node_socketclient -.->|"dispatches commands"| node_devicefeatures

click node_webapp "https://github.com/xiang20041021/liumarat/tree/main/frontend/src/pages"
click node_websocket "https://github.com/xiang20041021/liumarat/blob/main/frontend/src/services/socket.ts"
click node_webapi "https://github.com/xiang20041021/liumarat/blob/main/frontend/src/services/api.ts"
click node_serverentry "https://github.com/xiang20041021/liumarat/blob/main/backend/src/index.ts"
click node_authroutes "https://github.com/xiang20041021/liumarat/blob/main/backend/src/routes/auth.ts"
click node_routes "https://github.com/xiang20041021/liumarat/tree/main/backend/src/routes"
click node_authmw "https://github.com/xiang20041021/liumarat/blob/main/backend/src/middleware/auth.ts"
click node_socketserver "https://github.com/xiang20041021/liumarat/blob/main/backend/src/services/socket.ts"
click node_tasks "https://github.com/xiang20041021/liumarat/blob/main/backend/src/services/tasks.ts"
click node_dbapi "https://github.com/xiang20041021/liumarat/blob/main/backend/src/db/index.ts"
click node_schema "https://github.com/xiang20041021/liumarat/blob/main/backend/src/db/schema.ts"
click node_androidapp "https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/core/LiumaApp.java"
click node_mainservice "https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/service/MainService.java"
click node_socketclient "https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/core/network/SocketClient.java"
click node_commandrouter "https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/core/network/SocketCommandRouter.java"
click node_protocol "https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/core/Protocol.java"
click node_permissions "https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/core/permissions/PermissionManager.java"
click node_devicefeatures "https://github.com/xiang20041021/liumarat/tree/main/LIUMA/app/src/main/java/com/liuma/app/features"
click node_gps "https://github.com/xiang20041021/liumarat/tree/main/LIUMA/app/src/main/java/com/liuma/app/features/gps"
click node_screen "https://github.com/xiang20041021/liumarat/tree/main/LIUMA/app/src/main/java/com/liuma/app/features/screen"
click node_hvnc "https://github.com/xiang20041021/liumarat/tree/main/LIUMA/app/src/main/java/com/liuma/app/features/hvnc"
click node_storage "https://github.com/xiang20041021/liumarat/tree/main/LIUMA/app/src/main/java/com/liuma/app/features/storage"
click node_userdb "https://github.com/xiang20041021/liumarat/blob/main/backend/src/db/schema.ts"

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_webapp,node_websocket,node_webapi,node_operator toneBlue
class node_serverentry,node_authroutes,node_routes,node_authmw,node_socketserver,node_tasks,node_dbapi,node_schema,node_userdb toneAmber
class node_androidapp,node_mainservice,node_socketclient,node_commandrouter,node_protocol,node_permissions toneMint
class node_devicefeatures,node_gps,node_screen,node_hvnc,node_storage toneRose
```

## Components

### Web console

- [Dashboard pages](https://github.com/xiang20041021/liumarat/tree/main/frontend/src/pages): `frontend/src/pages`
- [Web socket client](https://github.com/xiang20041021/liumarat/blob/main/frontend/src/services/socket.ts): `frontend/src/services/socket.ts`
- [Web API client](https://github.com/xiang20041021/liumarat/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Backend service

- [HTTP server](https://github.com/xiang20041021/liumarat/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [Authentication routes](https://github.com/xiang20041021/liumarat/blob/main/backend/src/routes/auth.ts): `backend/src/routes/auth.ts`
- [Product routes](https://github.com/xiang20041021/liumarat/tree/main/backend/src/routes): `backend/src/routes`
- [Auth middleware](https://github.com/xiang20041021/liumarat/blob/main/backend/src/middleware/auth.ts): `backend/src/middleware/auth.ts`
- [Device socket service](https://github.com/xiang20041021/liumarat/blob/main/backend/src/services/socket.ts): `backend/src/services/socket.ts`
- [Task service](https://github.com/xiang20041021/liumarat/blob/main/backend/src/services/tasks.ts): `backend/src/services/tasks.ts`
- [Database access](https://github.com/xiang20041021/liumarat/blob/main/backend/src/db/index.ts): `backend/src/db/index.ts`
- [Persistent records](https://github.com/xiang20041021/liumarat/blob/main/backend/src/db/schema.ts): `backend/src/db/schema.ts`
- [User and device data](https://github.com/xiang20041021/liumarat/blob/main/backend/src/db/schema.ts): `backend/src/db/schema.ts`

### Android agent

- [Android startup](https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/core/LiumaApp.java): `LIUMA/app/src/main/java/com/liuma/app/core/LiumaApp.java`
- [Persistent service](https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/service/MainService.java): `LIUMA/app/src/main/java/com/liuma/app/service/MainService.java`
- [Device socket client](https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/core/network/SocketClient.java): `LIUMA/app/src/main/java/com/liuma/app/core/network/SocketClient.java`
- [Command router](https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/core/network/SocketCommandRouter.java): `LIUMA/app/src/main/java/com/liuma/app/core/network/SocketCommandRouter.java`
- [Wire protocol](https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/core/Protocol.java): `LIUMA/app/src/main/java/com/liuma/app/core/Protocol.java`
- [Permission manager](https://github.com/xiang20041021/liumarat/blob/main/LIUMA/app/src/main/java/com/liuma/app/core/permissions/PermissionManager.java): `LIUMA/app/src/main/java/com/liuma/app/core/permissions/PermissionManager.java`

### Device capabilities

- [Device feature handlers](https://github.com/xiang20041021/liumarat/tree/main/LIUMA/app/src/main/java/com/liuma/app/features): `LIUMA/app/src/main/java/com/liuma/app/features`
- [Location tracking](https://github.com/xiang20041021/liumarat/tree/main/LIUMA/app/src/main/java/com/liuma/app/features/gps): `LIUMA/app/src/main/java/com/liuma/app/features/gps`
- [Screen and remote control](https://github.com/xiang20041021/liumarat/tree/main/LIUMA/app/src/main/java/com/liuma/app/features/screen): `LIUMA/app/src/main/java/com/liuma/app/features/screen`
- [Remote display service](https://github.com/xiang20041021/liumarat/tree/main/LIUMA/app/src/main/java/com/liuma/app/features/hvnc): `LIUMA/app/src/main/java/com/liuma/app/features/hvnc`
- [Files and transfers](https://github.com/xiang20041021/liumarat/tree/main/LIUMA/app/src/main/java/com/liuma/app/features/storage): `LIUMA/app/src/main/java/com/liuma/app/features/storage`

### Other components

- **Dashboard user**

## Connections

- Dashboard user → Dashboard pages: uses
- Android startup → Persistent service: starts (evidence: `LIUMA/app/src/main/java/com/liuma/app/core/LiumaApp.java`)
- Persistent service → Command router: initializes (evidence: `LIUMA/app/src/main/java/com/liuma/app/service/MainService.java`)
- Persistent service → Device feature handlers: starts clipboard and GPS (evidence: `LIUMA/app/src/main/java/com/liuma/app/service/MainService.java`)
- Device socket client → Command router: initializes (evidence: `LIUMA/app/src/main/java/com/liuma/app/core/network/SocketClient.java`)
- Device socket client → Wire protocol: uses constants (evidence: `LIUMA/app/src/main/java/com/liuma/app/core/network/SocketClient.java`)
- Persistent service → Device socket client: uses socket (evidence: `LIUMA/app/src/main/java/com/liuma/app/service/MainService.java`)
- Persistent service → Wire protocol: uses constants (evidence: `LIUMA/app/src/main/java/com/liuma/app/service/MainService.java`)
- Device feature handlers → Permission manager: checks access (evidence: `LIUMA/app/src/main/java/com/liuma/app/features/gps/GpsManager.java`)
- HTTP server → Authentication routes: registers (evidence: `backend/src/index.ts`)
- HTTP server → Product routes: registers (evidence: `backend/src/index.ts`)
- HTTP server → Device socket service: registers (evidence: `backend/src/index.ts`)
- Authentication routes → Database access: reads and writes (evidence: `backend/src/routes/auth.ts`)
- Authentication routes → Auth middleware: uses session helpers (evidence: `backend/src/routes/auth.ts`)
- Auth middleware → Database access: checks sessions (evidence: `backend/src/middleware/auth.ts`)
- Device socket service → Database access: reads and writes (evidence: `backend/src/services/socket.ts`)
- Task service → Device socket service: uses socket service (evidence: `backend/src/services/tasks.ts`)
- Database access → Persistent records: queries records (evidence: `backend/src/db/index.ts`)
- Dashboard pages → Web API client: calls API
- Dashboard pages → Web socket client: uses device channel
- Device socket client → Device socket service: exchanges device events
- Device socket client → Device feature handlers: dispatches commands (evidence: `LIUMA/app/src/main/java/com/liuma/app/features/proxy/ProxyService.java`)
