Damselfly

Damselfly is a self‑hosted, server‑centric photo management system written in C# on the .NET 6/7 stack. It exposes a RESTful API for programmatic access while providing a rich web UI that runs in any modern browser. The core of the application is built around an Entity Framework Core data model that maps image metadata, tags, and machine‑learning annotations to a relational database (PostgreSQL or Microsoft SQL Server). A background worker service, implemented with IHostedService, continuously scans a folder hierarchy for new or updated files, extracts EXIF data with ExifTool, and stores thumbnails in a Redis cache for ultra‑fast retrieval. The entire stack is Docker‑friendly, allowing deployments on any platform that supports .NET containers.

Technical Stack & Architecture

• Language & Runtime: C# (.NET 6/7) on Windows, Linux, or macOS.
• Web Layer: ASP.NET Core MVC with Razor Pages for the UI and a dedicated Damselfly.Api project exposing JSON endpoints.
• Data Layer: Entity Framework Core ORM; supports PostgreSQL, SQL Server, and SQLite for lightweight setups.
• Background Processing: Hosted services (IHostedService) orchestrate image indexing, thumbnail generation, and ML inference.
• Machine Learning: Integrates with Azure Cognitive Services (Face API) for facial recognition, and an on‑prem OpenCV/ML.NET pipeline for object detection.
• Caching & Search: Redis serves as an in‑memory cache for thumbnails and full‑text search indexes powered by Lucene.NET.
• Desktop Client: Electron.Net bundles a cross‑platform desktop app that syncs server baskets to local directories, leveraging the same API surface.

Core Capabilities & APIs

• Fast Full‑Text Search: Lucene.NET indexes image titles, tags, and extracted captions; supports multi‑phrase and partial word queries with <1 s latency on 500k+ images.
• Advanced Filters: API endpoints allow filtering by date range, camera model, file size, orientation, and ML‑derived attributes (faces, objects).
• Batch Operations: Endpoints for moving/copying images between folders, trashing, and bulk tagging with non‑destructive EXIF updates via ExifTool.
• Baskets & Export: User‑specific or shared baskets can be queried, exported as ZIPs, watermarked, or pushed to WordPress through a webhook.
• Webhooks & Events: The system emits events on image addition, tag change, or ML inference completion; developers can subscribe to receive JSON payloads for downstream automation.
• Extensibility Hooks: A plugin architecture exposes IDamselflyPlugin interfaces, allowing custom ML models or UI extensions to be dropped into the Plugins/ folder without recompilation.

Deployment & Infrastructure

Damselfly ships as a Docker Compose stack with separate services for the API, database, Redis, and optional Azure Face Service credentials. The Docker images are small (≈200 MB) due to .NET's trimmed runtime, making it suitable for VPS or Kubernetes clusters. For large collections, the background workers can be scaled horizontally; Redis clustering ensures consistent caching across nodes. The application’s stateless API design means that any number of web front‑ends can be load‑balanced behind an NGINX or Traefik reverse proxy, providing high availability.

Integration & Extensibility

Developers can easily integrate Damselfly into existing workflows:

• CMS Integration: Use the export webhook to push images directly to WordPress or Drupal media libraries.
• CI/CD Pipelines: Trigger re‑indexing after a nightly backup restores new images.
• Custom ML Pipelines: Replace the default Azure Face API with a local TensorFlow model by implementing IFaceRecognizer in a plugin.
• UI Customization: Themes are supplied as Razor component libraries; developers can override CSS or add new components via the plugin system.

Developer Experience

The project follows standard .NET conventions, with comprehensive XML documentation and an interactive Swagger UI for API exploration. The codebase is open source on GitHub, with a dedicated issues tracker and community Discord channel for rapid support. Configuration is externalized via appsettings.json and environment variables, enabling seamless transition between dev, staging, and production environments. The documentation includes migration guides for database upgrades and detailed explanations of the background worker pipeline.

Use Cases

• Enterprise Photo Repositories: Large agencies can host a central catalog that all staff access, with automated tagging and facial recognition to quickly locate personnel photos.
• Digital Asset Management for Media: Journalists can tag and export images to CMSs or social media platforms directly from the web UI, accelerating content production.
• Personal Photo Archiving: Hobbyists can maintain a searchable library on a home NAS, leveraging the desktop client to sync edited photos back to the server.
• Research Projects: Scientists needing rapid visual similarity searches across millions of images can deploy Damselfly on a GPU‑enabled server to harness its ML inference capabilities.

Advantages

• Performance: Sub‑second search on half a million images, thanks to Lucene.NET and Redis caching.
• Flexibility: The plugin architecture allows swapping out ML backends or adding new UI components without touching core code.
• Licensing: MIT‑licensed source ensures