Personal Data Logger

Personal Data Logger is a .NET 10 background service that polls an IMAP inbox, processes supported email events, executes timed logs, and forwards the resulting events to a Personal Log Manager API.

📑 Table of Contents

• Capabilities
• Usage
• Known Limitations
• System Requirements
• Installation
• Configuration
• Project Structure
• Architecture
• Development
• Deployment
• Contributing
• Code of Conduct
• Security
• Privacy and Data
• Project Engagement
• License

✨ Capabilities

• Connects to an IMAP server and reads inbox emails
• Polls continuously (every 5 seconds)
• Reconnects automatically after transient IMAP connection failures while retaining the requested UID
• Keeps a persistent checkpoint based on IMAP UID to prevent duplicate processing
• Applies maximum email age filtering
• Retrieves Profi Bot Server account balances at configured local times
• Processes email events from multiple platforms (AliExpress, Discord, Gandi, Google, PayPal, Profi), including English and Romanian Google security-alert subjects
• Detects and handles Opsgenie on-call rotation notifications
• Converts timestamps to Romanian time (Europe/Bucharest) before sending to the API

🚀 Usage

dotnet run --project PersonalDataLogger/PersonalDataLogger.csproj

⚠️ Known Limitations

• Transient IMAP connection failures are retried indefinitely at five-second intervals. Authentication, email processing, and checkpoint persistence failures are not retried and terminate the worker.
• Events sent to the Personal Log Manager API are not queued locally or retried after an HTTP failure.

🖥️ System Requirements

Component	Minimum	Recommended
.NET SDK/Runtime	.NET 10.0	.NET 10.0 LTS
Operating System	Linux, macOS, Windows	Linux
RAM	256 MB	512 MB
Network	IMAP and API connectivity	Dedicated network access

📦 Installation

Installation from Source

git clone https://github.com/hmlendea/personal-data-logger.git
cd personal-data-logger
dotnet build personal-data-logger.slnx
dotnet run --project PersonalDataLogger/PersonalDataLogger.csproj

⚙️ Configuration

Configuration Files

File	Scope	Purpose
appsettings.json	Application	IMAP, API, and service settings

Secret Management

Sensitive configuration must be supplied through environment-specific configuration or secure secret-management systems. Never commit the following to version control:

• API keys and HMAC secrets for personalLogManagerSettings
• IMAP server credentials
• Profi Bot Server API keys and HMAC secrets

Configuration example:

{
  "personalLogManagerSettings": {
    "baseUrl": "https://example.local",
    "apiKey": "<api-key>",
    "hmacSharedSecretKey": "<hmac-secret>",
    "clientId": "<client-id>"
  },
  "imapSettings": {
    "server": "imap.example.local",
    "port": 993,
    "username": "user@example.local",
    "password": "<password>",
    "maxEmailAge": 1800
  },
  "personalSettings": {
    "employerName": "My Employer"
  },
  "aliExpressSettings": {
    "emailAddress": "user@example.local"
  },
  "profiBotServerSettings": {
    "accountName": "Hori",
    "scheduledHours": "06:30,18:00",
    "accountsEndpoint": "/Users/{username}/accounts",
    "baseUrl": "https://profi.example.local",
    "clientId": "Bruno",
    "hmacSharedSecretKey": "<hmac-secret>",
    "userApiKey": "<user-api-key>",
    "username": "hori"
  },
  "nuciLoggerSettings": {
    "minimumLevel": "Debug",
    "logFilePath": "logfile.log",
    "isFileOutputEnabled": true
  }
}

profiBotServerSettings.scheduledHours accepts one or more comma-separated times in HH:mm format. Each configured time runs once per day in the server's local time zone.

🗂️ Project Structure

The repository contains a .NET solution with separate application and unit-test projects.

Projects and Packages

Project	Type	Purpose
PersonalDataLogger/PersonalDataLogger.csproj	Executable	Background service for collecting and forwarding personal events
PersonalDataLogger.UnitTests/PersonalDataLogger.UnitTests.csproj	NUnit test project	Unit tests for the application services and processors

Directories

Directory	Purpose
PersonalDataLogger/Service/	Email polling, timed log execution, and email processors
PersonalDataLogger/Client/	API client services and Profi account management
PersonalDataLogger/Configuration/	Configuration model classes
PersonalDataLogger/Logging/	Logging operation and key definitions

🏗️ Architecture

See the architecture documentation for the system context, principal components, runtime flows, ownership boundaries, dependencies, constraints, and extension points.

Agent-oriented traceability is available in the feature map, code map, and documentation coverage audit.

🛠️ Development

Requirements

• .NET 10.0 SDK

Setup

git clone https://github.com/hmlendea/personal-data-logger.git
cd personal-data-logger
dotnet restore personal-data-logger.slnx

Build

dotnet build personal-data-logger.slnx

Run

dotnet run --project PersonalDataLogger/PersonalDataLogger.csproj

Test

dotnet test personal-data-logger.slnx

Release

The repository includes release.sh, which delegates to the upstream deployment script used by the project maintainer.

bash ./release.sh 1.0.0

This script downloads and executes an external release helper from https://raw.githubusercontent.com/hmlendea/deployment-scripts/master/release/dotnet/10.0.sh.

Note: Piping into bash is an intensely controversial topic. Please review any external scripts before running them in your environment!

Dependencies

Package	Version	Scope	Purpose
NuciLog	Latest	Runtime	Structured logging and diagnostics

🚢 Deployment

The service is designed to run as a background process on a host with network access to the configured IMAP server and Personal Log Manager API. It maintains application state in imap-checkpoint.json to track processed emails and prevent duplicate processing.

Configuration and Secrets

Sensitive configuration (API keys, HMAC secrets, IMAP passwords) must be supplied through environment-specific configuration and never committed to the repository. Use secure secret management systems for production deployments.

🤝 Contributing

You are welcome to submit any suggestion, feedback, or modification to this project.

When doing so, please:

• Maintain cross-platform compatibility
• Submit focused pull requests that conform to the existing code style
• Maintain your branch synchronised with master
• Revise the documentation when functionality changes
• Properly test all modifications, including edge cases and error conditions
• Include tests for additional or modified functionality
• Raise a new issue for problems or suggestions

See the contributing guidelines for details on how to report issues, suggest enhancements, and submit changes.

📜 Code of Conduct

See the Code of Conduct for the standards of conduct expected in all project spaces.

🔒 Security

Personal Data Logger handles sensitive configuration including API keys, HMAC secrets, and IMAP credentials. For information on reporting security vulnerabilities, see SECURITY.md.

🛡️ Privacy and Data

Personal Data Logger processes personal email data and configuration credentials. For the detailed description of how the application handles privacy and personal data, see PRIVACY.md.

💝 Project Engagement

Discovered a problem or have a suggestion? Open an issue!

If you find this project useful, consider funding it or starring ⭐️ it on GitHub!

📄 License

This project is being distributed under the GNU General Public License v3.0 or later. See LICENSE for additional information.