# clarky0505/cpp_tlfss architecture

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

- Interactive diagram: https://gitdiagram.com/clarky0505/cpp_tlfss
- Repository: https://github.com/clarky0505/cpp_tlfss

## Overview

TLSS is a single-node file storage service. Its principal workflow runs from the interactive client over the custom TCP Reactor to the storage service, which authenticates users, handles virtual-directory and file commands, and coordinates metadata with MySQL and file contents with asynchronous disk transfer. Monitoring and optimized memory copying are distinct subsystems; the README describes monitoring as independently run rather than started by the main service. Some subsystem links rely on README documentation because implementation excerpts are incomplete.

Main entry points: [`src/ftp/server.cpp`](https://github.com/clarky0505/cpp_tlfss/blob/main/src/ftp/server.cpp) (Command service), [`src/monitor/engine.cpp`](https://github.com/clarky0505/cpp_tlfss/blob/main/src/monitor/engine.cpp) (Monitor engine), [`src/ftp/service_engine.cpp`](https://github.com/clarky0505/cpp_tlfss/blob/main/src/ftp/service_engine.cpp) (Storage engine), [`src/common/net/event_loop.cpp`](https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/net/event_loop.cpp) (TCP Reactor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_cli["Interactive client<br/>[client.cpp]"]
  node_tcpclient["TCP client<br/>[tcp_client.cpp]"]
end

subgraph group_service["Storage service"]
  node_service["Command service<br/>[server.cpp]"]
  node_auth["Authentication<br/>[auth_service.cpp]"]
  node_users["User repository"]
  node_storage["Storage engine<br/>[service_engine.cpp]"]
  node_transfer["File transfer<br/>[file_transfer.h]"]
  node_disk["Async disk I/O"]
  node_objects[("SHA-256 objects<br/>[file_transfer.h]")]
end

subgraph group_platform["Runtime platform"]
  node_reactor["TCP Reactor<br/>[event_loop.cpp]"]
  node_tcpserver["TCP server<br/>[tcp_server.cpp]"]
  node_workers["Worker pool"]
  node_dbpool["MySQL pool"]
  node_buffer["Network buffer<br/>[buffer.cpp]"]
end

subgraph group_monitor["Monitoring"]
  node_monitorengine["Monitor engine<br/>[engine.cpp]"]
  node_monitorstore[("Metric store<br/>[monitor_store.cpp]")]
  node_monitorcli["Monitor CLI<br/>[cli_server.cpp]"]
  node_udp["UDP metrics<br/>[udp_publisher.cpp]"]
  node_alarms["Reliable alarms"]
end

subgraph group_memory["Memory copy"]
  node_memcopy["Copy dispatcher"]
end

node_user(("CLI user"))
node_mysql[("MySQL")]

node_user -->|"issues commands"| node_cli
node_cli -->|"connects through"| node_tcpclient
node_tcpclient -->|"uses event loop"| node_reactor
node_tcpserver -.->|"runs on"| node_reactor
node_reactor -->|"dispatches requests"| node_service
node_service -->|"submits work"| node_workers
node_service -->|"authenticates users"| node_auth
node_auth -->|"queries and creates users"| node_users
node_users -->|"borrows connections"| node_dbpool
node_storage -->|"borrows connections"| node_dbpool
node_dbpool -->|"manages connections"| node_mysql
node_service -->|"handles namespace metadata"| node_storage
node_service -->|"coordinates transfers"| node_transfer
node_transfer -->|"uses asynchronous I/O"| node_disk
node_disk -->|"publishes file objects"| node_objects
node_storage -->|"records object hash"| node_objects
node_monitorengine -->|"reads and updates"| node_monitorstore
node_monitorcli -.->|"accesses monitoring"| node_monitorengine
node_monitorengine -.->|"publishes metrics"| node_udp
node_monitorengine -.->|"supports reliable alarms"| node_alarms
node_buffer -->|"uses default copy"| node_memcopy

click node_cli "https://github.com/clarky0505/cpp_tlfss/blob/main/src/ftp/client.cpp"
click node_tcpclient "https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/net/tcp_client.cpp"
click node_reactor "https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/net/event_loop.cpp"
click node_tcpserver "https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/net/tcp_server.cpp"
click node_service "https://github.com/clarky0505/cpp_tlfss/blob/main/src/ftp/server.cpp"
click node_workers "https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/base/tlss_thread_pool.cpp"
click node_auth "https://github.com/clarky0505/cpp_tlfss/blob/main/src/auth/auth_service.cpp"
click node_users "https://github.com/clarky0505/cpp_tlfss/blob/main/src/auth/user_repository.cpp"
click node_dbpool "https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/base/mysql_connection_pool.cpp"
click node_storage "https://github.com/clarky0505/cpp_tlfss/blob/main/src/ftp/service_engine.cpp"
click node_transfer "https://github.com/clarky0505/cpp_tlfss/blob/main/inc/ftp/file_transfer.h"
click node_disk "https://github.com/clarky0505/cpp_tlfss/blob/main/src/ftp/async_file_receiver.cpp"
click node_objects "https://github.com/clarky0505/cpp_tlfss/blob/main/inc/ftp/file_transfer.h"
click node_monitorengine "https://github.com/clarky0505/cpp_tlfss/blob/main/src/monitor/engine.cpp"
click node_monitorstore "https://github.com/clarky0505/cpp_tlfss/blob/main/src/monitor/monitor_store.cpp"
click node_monitorcli "https://github.com/clarky0505/cpp_tlfss/blob/main/src/monitor/cli_server.cpp"
click node_udp "https://github.com/clarky0505/cpp_tlfss/blob/main/src/monitor/udp_publisher.cpp"
click node_alarms "https://github.com/clarky0505/cpp_tlfss/blob/main/src/monitor/reliable_alarm_collector.cpp"
click node_memcopy "https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/memory/memcpy_dispatch.cpp"
click node_buffer "https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/net/buffer.cpp"

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_cli,node_tcpclient,node_user toneBlue
class node_service,node_auth,node_users,node_storage,node_transfer,node_disk,node_objects,node_mysql toneAmber
class node_reactor,node_tcpserver,node_workers,node_dbpool,node_buffer toneMint
class node_monitorengine,node_monitorstore,node_monitorcli,node_udp,node_alarms toneRose
class node_memcopy toneIndigo
```

## Components

### Client

- [Interactive client](https://github.com/clarky0505/cpp_tlfss/blob/main/src/ftp/client.cpp): `src/ftp/client.cpp`
- [TCP client](https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/net/tcp_client.cpp): `src/common/net/tcp_client.cpp`

### Storage service

- [Command service](https://github.com/clarky0505/cpp_tlfss/blob/main/src/ftp/server.cpp): `src/ftp/server.cpp`
- [Authentication](https://github.com/clarky0505/cpp_tlfss/blob/main/src/auth/auth_service.cpp): `src/auth/auth_service.cpp`
- [User repository](https://github.com/clarky0505/cpp_tlfss/blob/main/src/auth/user_repository.cpp): `src/auth/user_repository.cpp`
- [Storage engine](https://github.com/clarky0505/cpp_tlfss/blob/main/src/ftp/service_engine.cpp): `src/ftp/service_engine.cpp`
- [File transfer](https://github.com/clarky0505/cpp_tlfss/blob/main/inc/ftp/file_transfer.h): `inc/ftp/file_transfer.h`
- [Async disk I/O](https://github.com/clarky0505/cpp_tlfss/blob/main/src/ftp/async_file_receiver.cpp): `src/ftp/async_file_receiver.cpp`
- [SHA-256 objects](https://github.com/clarky0505/cpp_tlfss/blob/main/inc/ftp/file_transfer.h): `inc/ftp/file_transfer.h`

### Runtime platform

- [TCP Reactor](https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/net/event_loop.cpp): `src/common/net/event_loop.cpp`
- [TCP server](https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/net/tcp_server.cpp): `src/common/net/tcp_server.cpp`
- [Worker pool](https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/base/tlss_thread_pool.cpp): `src/common/base/tlss_thread_pool.cpp`
- [MySQL pool](https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/base/mysql_connection_pool.cpp): `src/common/base/mysql_connection_pool.cpp`
- [Network buffer](https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/net/buffer.cpp): `src/common/net/buffer.cpp`

### Monitoring

- [Monitor engine](https://github.com/clarky0505/cpp_tlfss/blob/main/src/monitor/engine.cpp): `src/monitor/engine.cpp`
- [Metric store](https://github.com/clarky0505/cpp_tlfss/blob/main/src/monitor/monitor_store.cpp): `src/monitor/monitor_store.cpp`
- [Monitor CLI](https://github.com/clarky0505/cpp_tlfss/blob/main/src/monitor/cli_server.cpp): `src/monitor/cli_server.cpp`
- [UDP metrics](https://github.com/clarky0505/cpp_tlfss/blob/main/src/monitor/udp_publisher.cpp): `src/monitor/udp_publisher.cpp`
- [Reliable alarms](https://github.com/clarky0505/cpp_tlfss/blob/main/src/monitor/reliable_alarm_collector.cpp): `src/monitor/reliable_alarm_collector.cpp`

### Memory copy

- [Copy dispatcher](https://github.com/clarky0505/cpp_tlfss/blob/main/src/common/memory/memcpy_dispatch.cpp): `src/common/memory/memcpy_dispatch.cpp`

### Other components

- **CLI user**
- **MySQL**

## Connections

- CLI user → Interactive client: issues commands (evidence: `README.md`)
- Interactive client → TCP client: connects through
- TCP client → TCP Reactor: uses event loop
- TCP server → TCP Reactor: runs on
- TCP Reactor → Command service: dispatches requests (evidence: `README.md`)
- Command service → Worker pool: submits work
- Command service → Authentication: authenticates users
- Authentication → User repository: queries and creates users (evidence: `src/auth/auth_service.cpp`)
- User repository → MySQL pool: borrows connections (evidence: `src/auth/user_repository.cpp`)
- Storage engine → MySQL pool: borrows connections (evidence: `src/ftp/service_engine.cpp`)
- MySQL pool → MySQL: manages connections
- Command service → Storage engine: handles namespace metadata
- Command service → File transfer: coordinates transfers (evidence: `src/ftp/server.cpp`)
- File transfer → Async disk I/O: uses asynchronous I/O
- Async disk I/O → SHA-256 objects: publishes file objects
- Storage engine → SHA-256 objects: records object hash (evidence: `src/ftp/service_engine.cpp`)
- Monitor engine → Metric store: reads and updates (evidence: `src/monitor/engine.cpp`)
- Monitor CLI → Monitor engine: accesses monitoring
- Monitor engine → UDP metrics: publishes metrics
- Monitor engine → Reliable alarms: supports reliable alarms
- Network buffer → Copy dispatcher: uses default copy (evidence: `README.md`)