# 3. Core Concepts
A short map of the ideas you will see in the UI. Understanding these makes the rest of the guide much easier.
# Monitored folder
A monitored folder is a local path TotumService watches on a schedule (for example every 30 seconds).
When you add a folder you choose:
- Where to look (path)
- Which files to include or exclude (patterns like
*.pdf) - Where to upload (S3 bucket and optional prefix / “folder” in the bucket)
- Options such as recursive (include subfolders) and delete after upload
Configuration is done in the web UI: Configuration → Folders.
# File lifecycle (states)
Each discovered file moves through states. You will see these in Database Explorer and in help text on the Folders page.
| State | Meaning |
|---|---|
| Detected | File was found and recorded |
| Stable | File stopped changing long enough to be safe to upload |
| Uploading | Transfer is in progress |
| Uploaded | Cloud storage accepted the file |
| Failed | Upload failed; may retry |
| Failed Permanent | Retries exhausted; needs human attention |
Rough flow:
Detected → Stable → Uploading → Uploaded
↘ Failed → (retry) → … or Failed Permanent# Transfer
A transfer is one upload (or download) job handled by the transfer system. Large files may use multipart upload (many parts, one logical transfer).
You see transfers on:
- The dashboard (Active Transfers)
- Database Explorer (Transfers tab)
# Provider
A provider is a storage backend. In practice you will mostly use S3.
Providers can be enabled or disabled from the dashboard. Disabling stops new work through that provider; it does not erase history.
Connection details (API URL, API key, default bucket, region) live in configuration files — see Advanced.
# Plugin
TotumService is modular. Each plugin does one job, for example:
| Plugin | Role (in plain terms) |
|---|---|
| Folder Upload Monitor | Watches folders and requests uploads |
| File Transfer Coordinator | Queues and runs transfers |
| Web Monitoring | Hosts the dashboard and APIs |
| Media Monitoring | Finds Unity media/metrics JSON under user profiles |
| Media Upload Processor | Watches those media JSON files for changes |
| Logging | Controls file logging behaviour |
Plugins appear on the dashboard with a health status.
# Settings vs config files
| Kind | Where | Typical use |
|---|---|---|
| Plugin settings | Configuration → Settings tab | Day-to-day toggles and numbers (often live) |
| appsettings.json* | Next to the service executable | Buckets, API keys, ports, deep defaults |
If a setting is marked (Requires restart), change it in the UI, then restart the Windows service.
# Databases (why they matter)
TotumService stores state in local SQLite files under a Data folder, for example:
- Folder tracking
- Transfer queue / history
- Provider enable/disable state
- Plugin settings
You do not edit these by hand. Use Database Explorer and the dashboard’s Database Files section to understand what exists.
# Dashboard refresh
The main dashboard auto-refreshes (often every few seconds). You can turn auto-refresh off or click Refresh Now. Configuration and Database Explorer pages refresh when you ask them to (or when you change filters).