# olehov/sparenode architecture

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

- Interactive diagram: https://gitdiagram.com/olehov/sparenode
- Repository: https://github.com/olehov/sparenode

## Overview

SpareNode is a cross-platform file server for sharing configured folders over a local network. Its principal workflow is to load and validate the explicitly selected configuration, prepare server runtime plans, accept TCP connections, process bounded HTTP requests, route filesystem API operations, and return responses. Distinct supporting stages include safe shared-root and filesystem operations, request-body temporary storage, and owner authentication. The README also documents transport trust policies and structured logging. Several runtime details are not sampled, so the graph omits unsupported call relationships rather than inferring them.

Main entry points: [`apps/sparenode/server.cpp`](https://github.com/olehov/sparenode/blob/main/apps/sparenode/server.cpp) (Server composition), [`src/http/transport/http_connection_handler.cpp`](https://github.com/olehov/sparenode/blob/main/src/http/transport/http_connection_handler.cpp) (HTTP connection handler), [`src/application/filesystem_service.cpp`](https://github.com/olehov/sparenode/blob/main/src/application/filesystem_service.cpp) (Filesystem service), [`src/bootstrap/runtime_bootstrap.cpp`](https://github.com/olehov/sparenode/blob/main/src/bootstrap/runtime_bootstrap.cpp) (Runtime bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and configuration"]
  node_cli["Command-line options<br/>[command_line.cpp]"]
  node_config["Config parsing<br/>[config_parser.cpp]"]
  node_bootstrap["Runtime bootstrap"]
  node_server["Server composition<br/>[server.cpp]"]
end

subgraph group_network_http["Network and HTTP"]
  node_listener["TCP listener<br/>[tcp_listener.cpp]"]
  node_dispatcher["Connection dispatch"]
  node_http_handler["HTTP connection handler"]
  node_body_ingest["Request body ingestion"]
  node_router["HTTP router<br/>[http_router.cpp]"]
  node_api["Filesystem API routes<br/>[filesystem_api.cpp]"]
  node_response["HTTP responses<br/>[http_response.cpp]"]
end

subgraph group_filesystem["Shared filesystem"]
  node_fs_service["Filesystem service"]
  node_safe_path["Safe path boundary<br/>[safe_path.cpp]"]
  node_shared_root["Shared root<br/>[shared_root.cpp]"]
  node_fs_ops["Filesystem operations"]
  node_temp_storage["Temporary body storage"]
end

subgraph group_identity["Authentication"]
  node_auth_service["Authentication service"]
  node_credentials["File credentials"]
end

subgraph group_operations["Runtime operations"]
  node_logging["Structured logging<br/>[logger.cpp]"]
end

node_operator(("Server operator"))

node_operator -->|"provides options"| node_cli
node_server -->|"loads configuration"| node_config
node_server -->|"prepares runtime"| node_bootstrap
node_server -->|"builds filesystem API"| node_api
node_server -->|"creates router"| node_router
node_server -->|"configures handler"| node_http_handler
node_listener -.->|"schedules connections"| node_dispatcher
node_dispatcher -->|"dispatches connections"| node_http_handler
node_http_handler -->|"ingests request bodies"| node_body_ingest
node_http_handler -.->|"dispatches requests"| node_router
node_http_handler -->|"writes responses"| node_response
node_api -->|"registers routes"| node_router
node_api -->|"composes filesystem service"| node_fs_service
node_fs_service -.->|"validates paths"| node_safe_path
node_fs_service -->|"performs operations"| node_fs_ops
node_fs_service -->|"materializes uploads"| node_temp_storage
node_bootstrap -->|"validates share root"| node_shared_root
node_bootstrap -->|"prepares authentication"| node_auth_service
node_auth_service -.->|"looks up credentials"| node_credentials
node_server -->|"emits lifecycle logs"| node_logging

click node_cli "https://github.com/olehov/sparenode/blob/main/src/application/command_line.cpp"
click node_config "https://github.com/olehov/sparenode/blob/main/src/configuration/config_parser.cpp"
click node_bootstrap "https://github.com/olehov/sparenode/blob/main/src/bootstrap/runtime_bootstrap.cpp"
click node_server "https://github.com/olehov/sparenode/blob/main/apps/sparenode/server.cpp"
click node_listener "https://github.com/olehov/sparenode/blob/main/src/network/tcp_listener.cpp"
click node_dispatcher "https://github.com/olehov/sparenode/blob/main/src/network/connection_dispatcher.cpp"
click node_http_handler "https://github.com/olehov/sparenode/blob/main/src/http/transport/http_connection_handler.cpp"
click node_body_ingest "https://github.com/olehov/sparenode/blob/main/src/http/transport/request_body_ingestor.cpp"
click node_router "https://github.com/olehov/sparenode/blob/main/src/http/routing/http_router.cpp"
click node_api "https://github.com/olehov/sparenode/blob/main/src/http/api/filesystem_api.cpp"
click node_response "https://github.com/olehov/sparenode/blob/main/src/http/response/http_response.cpp"
click node_fs_service "https://github.com/olehov/sparenode/blob/main/src/application/filesystem_service.cpp"
click node_safe_path "https://github.com/olehov/sparenode/blob/main/src/filesystem/safe_path.cpp"
click node_shared_root "https://github.com/olehov/sparenode/blob/main/src/filesystem/shared_root.cpp"
click node_fs_ops "https://github.com/olehov/sparenode/tree/main/src/filesystem"
click node_temp_storage "https://github.com/olehov/sparenode/blob/main/src/storage/temporary_file_writer.cpp"
click node_auth_service "https://github.com/olehov/sparenode/blob/main/src/authentication/authentication_service.cpp"
click node_credentials "https://github.com/olehov/sparenode/blob/main/src/authentication/file_authentication.cpp"
click node_logging "https://github.com/olehov/sparenode/blob/main/src/logging/logger.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_config,node_bootstrap,node_server toneBlue
class node_listener,node_dispatcher,node_http_handler,node_body_ingest,node_router,node_api,node_response toneAmber
class node_fs_service,node_safe_path,node_shared_root,node_fs_ops,node_temp_storage,node_operator toneMint
class node_auth_service,node_credentials toneRose
class node_logging toneIndigo
```

## Components

### Startup and configuration

- [Command-line options](https://github.com/olehov/sparenode/blob/main/src/application/command_line.cpp): `src/application/command_line.cpp`
- [Config parsing](https://github.com/olehov/sparenode/blob/main/src/configuration/config_parser.cpp): `src/configuration/config_parser.cpp`
- [Runtime bootstrap](https://github.com/olehov/sparenode/blob/main/src/bootstrap/runtime_bootstrap.cpp): `src/bootstrap/runtime_bootstrap.cpp`
- [Server composition](https://github.com/olehov/sparenode/blob/main/apps/sparenode/server.cpp): `apps/sparenode/server.cpp`

### Network and HTTP

- [TCP listener](https://github.com/olehov/sparenode/blob/main/src/network/tcp_listener.cpp): `src/network/tcp_listener.cpp`
- [Connection dispatch](https://github.com/olehov/sparenode/blob/main/src/network/connection_dispatcher.cpp): `src/network/connection_dispatcher.cpp`
- [HTTP connection handler](https://github.com/olehov/sparenode/blob/main/src/http/transport/http_connection_handler.cpp): `src/http/transport/http_connection_handler.cpp`
- [Request body ingestion](https://github.com/olehov/sparenode/blob/main/src/http/transport/request_body_ingestor.cpp): `src/http/transport/request_body_ingestor.cpp`
- [HTTP router](https://github.com/olehov/sparenode/blob/main/src/http/routing/http_router.cpp): `src/http/routing/http_router.cpp`
- [Filesystem API routes](https://github.com/olehov/sparenode/blob/main/src/http/api/filesystem_api.cpp): `src/http/api/filesystem_api.cpp`
- [HTTP responses](https://github.com/olehov/sparenode/blob/main/src/http/response/http_response.cpp): `src/http/response/http_response.cpp`

### Shared filesystem

- [Filesystem service](https://github.com/olehov/sparenode/blob/main/src/application/filesystem_service.cpp): `src/application/filesystem_service.cpp`
- [Safe path boundary](https://github.com/olehov/sparenode/blob/main/src/filesystem/safe_path.cpp): `src/filesystem/safe_path.cpp`
- [Shared root](https://github.com/olehov/sparenode/blob/main/src/filesystem/shared_root.cpp): `src/filesystem/shared_root.cpp`
- [Filesystem operations](https://github.com/olehov/sparenode/tree/main/src/filesystem): `src/filesystem`
- [Temporary body storage](https://github.com/olehov/sparenode/blob/main/src/storage/temporary_file_writer.cpp): `src/storage/temporary_file_writer.cpp`

### Authentication

- [Authentication service](https://github.com/olehov/sparenode/blob/main/src/authentication/authentication_service.cpp): `src/authentication/authentication_service.cpp`
- [File credentials](https://github.com/olehov/sparenode/blob/main/src/authentication/file_authentication.cpp): `src/authentication/file_authentication.cpp`

### Runtime operations

- [Structured logging](https://github.com/olehov/sparenode/blob/main/src/logging/logger.cpp): `src/logging/logger.cpp`

### Other components

- **Server operator**

## Connections

- Server operator → Command-line options: provides options (evidence: `README.md`)
- Server composition → Config parsing: loads configuration (evidence: `apps/sparenode/server.cpp`)
- Server composition → Runtime bootstrap: prepares runtime (evidence: `apps/sparenode/server.cpp`)
- Server composition → Filesystem API routes: builds filesystem API (evidence: `apps/sparenode/server.cpp`)
- Server composition → HTTP router: creates router (evidence: `apps/sparenode/server.cpp`)
- Server composition → HTTP connection handler: configures handler (evidence: `apps/sparenode/server.cpp`)
- TCP listener → Connection dispatch: schedules connections
- Connection dispatch → HTTP connection handler: dispatches connections
- HTTP connection handler → Request body ingestion: ingests request bodies
- HTTP connection handler → HTTP router: dispatches requests
- HTTP connection handler → HTTP responses: writes responses (evidence: `src/http/transport/http_connection_handler.cpp`)
- Filesystem API routes → HTTP router: registers routes
- Filesystem API routes → Filesystem service: composes filesystem service
- Filesystem service → Safe path boundary: validates paths
- Filesystem service → Filesystem operations: performs operations
- Filesystem service → Temporary body storage: materializes uploads
- Runtime bootstrap → Shared root: validates share root (evidence: `src/bootstrap/runtime_bootstrap.cpp`)
- Runtime bootstrap → Authentication service: prepares authentication
- Authentication service → File credentials: looks up credentials
- Server composition → Structured logging: emits lifecycle logs (evidence: `apps/sparenode/server.cpp`)
