# gonzalopinheiro/homedb architecture

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

- Interactive diagram: https://gitdiagram.com/gonzalopinheiro/homedb
- Repository: https://github.com/gonzalopinheiro/homedb

## Overview

HomeDB is a self-hosted file and account management API: authenticated users can upload files and organize folders, while administrators manage users, permissions, backups, logs, and monitoring. The main request path is HTTP controller to application service, then repositories and storage, returning API responses. Additional branches provide authentication, auditing, background backup and monitoring, and asynchronous operational logging. The README contains no capability detail; those branches reflect the source tree. Unsampled controller/service links are documented here only where the supplied source index or excerpts support them.

Main entry points: [`HomeDB/Controllers`](https://github.com/gonzalopinheiro/homedb/tree/main/HomeDB/Controllers) (API controllers), [`HomeDB.Infrastructure/Repositories`](https://github.com/gonzalopinheiro/homedb/tree/main/HomeDB.Infrastructure/Repositories) (Data repositories), [`HomeDB.Application/Services/AuthService.cs`](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/AuthService.cs) (Authentication), [`HomeDB.Application/Services/UploadService.cs`](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/UploadService.cs) (Chunked uploads)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_controllers["API controllers"]
end

subgraph group_app["Application services"]
  node_auth["Authentication<br/>[AuthService.cs]"]
  node_files["File management<br/>[FilesService.cs]"]
  node_folders["Folder management<br/>[FoldersService.cs]"]
  node_uploads["Chunked uploads<br/>[UploadService.cs]"]
  node_useradmin["User administration"]
  node_permissions["Module permissions"]
  node_backup["Backup orchestration<br/>[BackupService.cs]"]
  node_audit["Audit service<br/>[AuditService.cs]"]
  node_metrics["Metrics service"]
end

subgraph group_infra["Infrastructure"]
  node_logging["Application logging<br/>[Logger.cs]"]
  node_logscope["Operation scope"]
  node_logworker["Log worker"]
  node_storage["File storage"]
  node_monitoring["System readers"]
  node_backupworker["Backup process"]
  node_database[("Application database<br/>[AppDbContext.cs]")]
  node_repositories["Data repositories<br/>[Repositories]"]
end

subgraph group_ops["Operations and admin"]
  node_authorization["Module authorization"]
  node_errorhandler["Error responses"]
  node_metricsworker["Metrics worker"]
  node_backupworkerhost["Backup worker"]
  node_uploadcleanup["Upload cleanup"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_controllers
node_controllers -->|"invokes"| node_auth
node_controllers -->|"invokes"| node_files
node_controllers -.->|"invokes"| node_folders
node_controllers -.->|"invokes"| node_uploads
node_controllers -->|"invokes"| node_useradmin
node_controllers -.->|"invokes"| node_permissions
node_controllers -.->|"invokes"| node_backup
node_controllers -.->|"invokes"| node_audit
node_controllers -.->|"invokes"| node_metrics
node_auth -->|"records events"| node_audit
node_auth -->|"uses data access"| node_repositories
node_uploads -->|"stores files"| node_storage
node_uploads -->|"uses data access"| node_repositories
node_useradmin -.->|"uses data access"| node_repositories
node_permissions -.->|"uses data access"| node_repositories
node_backup -.->|"runs process"| node_backupworker
node_backupworkerhost -.->|"dispatches"| node_backupworker
node_metricsworker -->|"updates metrics"| node_metrics
node_metricsworker -.->|"reads system"| node_monitoring
node_metrics -.->|"uses data access"| node_repositories
node_repositories -.->|"reads and writes"| node_database
node_controllers -.->|"checks access"| node_authorization
node_authorization -->|"checks permissions"| node_permissions
node_controllers -.->|"handled by pipeline"| node_errorhandler
node_errorhandler -->|"logs failures"| node_logging
node_logscope -->|"logs scope"| node_logging
node_logging -->|"enqueues entries"| node_logworker
node_logworker -->|"persists entries"| node_repositories
node_uploadcleanup -.->|"cleans sessions"| node_repositories

click node_controllers "https://github.com/gonzalopinheiro/homedb/tree/main/HomeDB/Controllers"
click node_auth "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/AuthService.cs"
click node_files "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/FilesService.cs"
click node_folders "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/FoldersService.cs"
click node_uploads "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/UploadService.cs"
click node_useradmin "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/UserAdminSettingsService.cs"
click node_permissions "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/UserModulePermissionsService.cs"
click node_backup "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/BackupService.cs"
click node_audit "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/AuditService.cs"
click node_metrics "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/SystemMetricsService.cs"
click node_logging "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Observability/Logger.cs"
click node_logscope "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Observability/OperationLogScope.cs"
click node_logworker "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Observability/LogBackgroundService.cs"
click node_storage "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Storage/FileStorageService.cs"
click node_monitoring "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/SystemMonitoring/LinuxSystemMetricsReader.cs"
click node_backupworker "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Backup/BackupProcessService.cs"
click node_database "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Data/AppDbContext.cs"
click node_repositories "https://github.com/gonzalopinheiro/homedb/tree/main/HomeDB.Infrastructure/Repositories"
click node_authorization "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB/Authorization/Handlers/ModuleAuthorizationHandler.cs"
click node_errorhandler "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB/Middlewares/ExceptionHandlerMiddleware.cs"
click node_metricsworker "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/SystemMonitoring/SystemMetricsBackgroundService.cs"
click node_backupworkerhost "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Backup/BackupBackgroundService.cs"
click node_uploadcleanup "https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Storage/UploadCleanupBackgroundService.cs"

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_controllers,node_client toneBlue
class node_auth,node_files,node_folders,node_uploads,node_useradmin,node_permissions,node_backup,node_audit,node_metrics toneAmber
class node_logging,node_logscope,node_logworker,node_storage,node_monitoring,node_backupworker,node_database,node_repositories toneMint
class node_authorization,node_errorhandler,node_metricsworker,node_backupworkerhost,node_uploadcleanup toneRose
```

## Components

### HTTP API

- [API controllers](https://github.com/gonzalopinheiro/homedb/tree/main/HomeDB/Controllers): `HomeDB/Controllers`

### Application services

- [Authentication](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/AuthService.cs): `HomeDB.Application/Services/AuthService.cs`
- [File management](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/FilesService.cs): `HomeDB.Application/Services/FilesService.cs`
- [Folder management](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/FoldersService.cs): `HomeDB.Application/Services/FoldersService.cs`
- [Chunked uploads](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/UploadService.cs): `HomeDB.Application/Services/UploadService.cs`
- [User administration](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/UserAdminSettingsService.cs): `HomeDB.Application/Services/UserAdminSettingsService.cs`
- [Module permissions](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/UserModulePermissionsService.cs): `HomeDB.Application/Services/UserModulePermissionsService.cs`
- [Backup orchestration](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/BackupService.cs): `HomeDB.Application/Services/BackupService.cs`
- [Audit service](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/AuditService.cs): `HomeDB.Application/Services/AuditService.cs`
- [Metrics service](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Application/Services/SystemMetricsService.cs): `HomeDB.Application/Services/SystemMetricsService.cs`

### Infrastructure

- [Application logging](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Observability/Logger.cs): `HomeDB.Infrastructure/Observability/Logger.cs`
- [Operation scope](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Observability/OperationLogScope.cs): `HomeDB.Infrastructure/Observability/OperationLogScope.cs`
- [Log worker](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Observability/LogBackgroundService.cs): `HomeDB.Infrastructure/Observability/LogBackgroundService.cs`
- [File storage](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Storage/FileStorageService.cs): `HomeDB.Infrastructure/Storage/FileStorageService.cs`
- [System readers](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/SystemMonitoring/LinuxSystemMetricsReader.cs): `HomeDB.Infrastructure/SystemMonitoring/LinuxSystemMetricsReader.cs`
- [Backup process](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Backup/BackupProcessService.cs): `HomeDB.Infrastructure/Backup/BackupProcessService.cs`
- [Application database](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Data/AppDbContext.cs): `HomeDB.Infrastructure/Data/AppDbContext.cs`
- [Data repositories](https://github.com/gonzalopinheiro/homedb/tree/main/HomeDB.Infrastructure/Repositories): `HomeDB.Infrastructure/Repositories`

### Operations and admin

- [Module authorization](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB/Authorization/Handlers/ModuleAuthorizationHandler.cs): `HomeDB/Authorization/Handlers/ModuleAuthorizationHandler.cs`
- [Error responses](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB/Middlewares/ExceptionHandlerMiddleware.cs): `HomeDB/Middlewares/ExceptionHandlerMiddleware.cs`
- [Metrics worker](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/SystemMonitoring/SystemMetricsBackgroundService.cs): `HomeDB.Infrastructure/SystemMonitoring/SystemMetricsBackgroundService.cs`
- [Backup worker](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Backup/BackupBackgroundService.cs): `HomeDB.Infrastructure/Backup/BackupBackgroundService.cs`
- [Upload cleanup](https://github.com/gonzalopinheiro/homedb/blob/main/HomeDB.Infrastructure/Storage/UploadCleanupBackgroundService.cs): `HomeDB.Infrastructure/Storage/UploadCleanupBackgroundService.cs`

### Other components

- **API client**

## Connections

- API client → API controllers: sends requests (evidence: `HomeDB/Controllers/AuthController.cs`)
- API controllers → Authentication: invokes (evidence: `HomeDB/Controllers/AuthController.cs`)
- API controllers → File management: invokes (evidence: `HomeDB/Controllers/FilesController.cs`)
- API controllers → Folder management: invokes
- API controllers → Chunked uploads: invokes
- API controllers → User administration: invokes (evidence: `HomeDB/Controllers/UsersSettingsController.cs`)
- API controllers → Module permissions: invokes
- API controllers → Backup orchestration: invokes
- API controllers → Audit service: invokes
- API controllers → Metrics service: invokes
- Authentication → Audit service: records events (evidence: `HomeDB.Application/Services/AuthService.cs`)
- Authentication → Data repositories: uses data access (evidence: `HomeDB.Application/Services/AuthService.cs`)
- Chunked uploads → File storage: stores files (evidence: `HomeDB.Application/Services/UploadService.cs`)
- Chunked uploads → Data repositories: uses data access (evidence: `HomeDB.Application/Services/UploadService.cs`)
- User administration → Data repositories: uses data access
- Module permissions → Data repositories: uses data access
- Backup orchestration → Backup process: runs process
- Backup worker → Backup process: dispatches
- Metrics worker → Metrics service: updates metrics (evidence: `HomeDB.Infrastructure/SystemMonitoring/SystemMetricsBackgroundService.cs`)
- Metrics worker → System readers: reads system
- Metrics service → Data repositories: uses data access
- Data repositories → Application database: reads and writes (evidence: `HomeDB.Infrastructure/Repositories/UploadSessionRepository.cs`)
- API controllers → Module authorization: checks access
- Module authorization → Module permissions: checks permissions (evidence: `HomeDB/Authorization/Handlers/ModuleAuthorizationHandler.cs`)
- API controllers → Error responses: handled by pipeline
- Error responses → Application logging: logs failures (evidence: `HomeDB/Middlewares/ExceptionHandlerMiddleware.cs`)
- Operation scope → Application logging: logs scope (evidence: `HomeDB.Infrastructure/Observability/OperationLogScope.cs`)
- Application logging → Log worker: enqueues entries (evidence: `HomeDB.Infrastructure/Observability/Logger.cs`)
- Log worker → Data repositories: persists entries (evidence: `HomeDB.Infrastructure/Observability/LogBackgroundService.cs`)
- Upload cleanup → Data repositories: cleans sessions
