Blue Steel HMC engineering
Architecture, decisions, and practices supporting a complete media experience.
Engineering details
Blue Steel HMC's architecture aims to separate responsibilities, keep media flows operable, and provide a foundation ready to evolve. These are the technical criteria and decisions supporting the product.
Technical overview
Architecture
Separated responsibilities
The solution follows Clean Architecture, with distinct responsibilities for business rules, use cases, persistence, integrations, and execution.
Server, client, and communication
Two connected experiences
The server owns the product capabilities while the Windows and Android apps connect through an API, real-time updates, and device authorization.
Media delivery
Streaming within the LAN
Playback on the same Windows PC is local. For Android or Chromecast, the Windows server streams the media within the LAN; Android can also control the Chromecast session.
Blue assistant
Local, isolated, verifiable RAG
Blue, the AI assistant, receives questions from the Windows and Android apps through the authenticated API. The API validates the session and conversation access, then delegates generation to a supervised local worker. The worker retrieves information from the manual and streams sourced answers, keeping inference on the Windows machine hosting Blue Steel.
Quality and operations
Verifiable continuity
Tests, logs, diagnostics, backups, and recovery complement the operation of catalog, ingestion, and playback flows.
Architecture and boundaries
Windows and Android apps
The apps support content discovery, session and profile management, media playback, and asking the assistant from within Blue Steel.
API and real-time communication
REST API, SignalR, and periodic polling as a fallback connect the client to server capabilities and keep playback state current.
Use cases and business rules
Use cases coordinate catalog, libraries, metadata, profiles, devices, ingestion, and playback without coupling the experience to infrastructure details.
Persistence, integrations, and execution
SQLite, the file system, TMDb, LibVLCSharp, mDNS/Zeroconf, logging, and background services support the product flows.
Decisions and tradeoffs
| Decision | Why | Benefit | Tradeoff and review |
|---|---|---|---|
| Windows server and Android client | Separate media operations from device access. | Centralized content control with an independent consumption experience. | Dependency on two product surfaces; review if new clients or independent deployment needs emerge. |
| REST API and SignalR | Combine explicit contracts with real-time state updates. | Interoperability and smooth synchronization of playback, ingestion, and activity. | More connection and state complexity; review resilience and versioning if consumers grow. |
| Periodic polling as a fallback | Keep an alternative available when real-time communication is unavailable. | The experience can continue querying state in variable connectivity scenarios. | More traffic and less immediacy; review intervals and need if real-time coverage improves. |
| SQLite and Entity Framework Core | Persist the catalog locally while maintaining an organized relational model. | Operational simplicity, productivity, and transactional consistency for the current scope. | Less margin for distributed or high-volume scenarios; review if scale or query needs change. |
| Background ingestion | Avoid blocking the experience while libraries are scanned and enriched. | Observable progress, pause, resume, and recovery from errors. | State, retry, and consistency complexity; review if volume or concurrency increases. |
| LibVLCSharp for playback | Integrate media capabilities into the client. | Playback controls, audio and subtitle selection in a unified experience. | Native media integration dependency; review compatibility if platforms or formats change. |
| TMDb for metadata | Enrich the catalog without maintaining all information manually. | More complete cast, crew, images, trailers, and genres. | Dependency on an external service and its limits; review caching and degradation if availability changes. |
| mDNS/Zeroconf for discovery | Make connecting to servers on the local network easier. | Onboarding with less manual configuration. | Dependency on network behavior; review alternatives if remote scenarios expand. |
Technology stack
Application
Experience and services
The product uses .NET, ASP.NET Core, and .NET MAUI Blazor Hybrid to organize the server and client experience.
Communication
Contracts and shared state
REST API, SignalR, and JWT support communication, state updates, and authorization for sessions and devices.
Data
Organized persistence
SQLite and Entity Framework Core organize access to the catalog, libraries, profiles, and playback state.
Media and integration
Services connected to the product
TMDb, LibVLCSharp, Chromecast, mDNS/Zeroconf, and the file system support metadata, playback, and discovery.
Operations
System continuity
Serilog, logs, diagnostics, background services, versioned backups, and protected restoration complement operations.
Local AI
Manual-grounded assistant
The RAG architecture retrieves relevant information from the manual to answer questions and show its sources. Inference runs locally on the Windows server through the model runtime integrated with Blue Steel.
Security, quality, and operations
Authorization and profiles
Explicit device authorization, trusted and managed devices, roles, guest user, configurable visibility, and PIN form part of the conceptual access model.
Testing and continuity
Unit tests validate rules and use cases, while integration tests focus on persistence and queries. Logs, diagnostics, versioned backups, restoration, and client recovery complement operational quality.
Scope and conversation lifecycle
The assistant is limited to the manual: it does not query the internet or live catalog, and it cannot perform actions. It should say when the document is insufficient. Conversations are shared across Windows and Android, may expire after inactivity, and are cleared when the server restarts.
Want to return to the product narrative?