Technology in detail

At a glance

Architecture

Backend and frontend follow Clean Architecture with four layers. Dependencies point inwards only:

• Domain depends on nothing: entities, rules, domain services.
• Application depends on Domain only: commands, queries, handlers, validation. No Entity Framework, no IQueryable.
• Infrastructure implements the ports: persistence, LLM providers, mail, geo services, ONNX models.
• Presentation means controllers, SignalR hubs and the MCP endpoint; in the frontend, the Angular components.

Commands and queries go through a custom mediator (not MediatR) with pipeline behaviors for validation (FluentValidation) and cancellation. Riok.Mapperly generates the mapping code at compile time instead of using reflection; a custom Roslyn source generator covers further boilerplate.

How we enforce the architecture

In the backend, the layers are folders and namespaces inside one assembly. That is why 75 architecture test classes scan the source on every test run, for example:

• Layer direction: no EF Core in Domain and Application, Presentation never reaches into Infrastructure.
• File size: no file above 800 lines, no method above 150 lines.
• One type per file, file name equals type name.
• Every controller and SignalR hub pins the JWT scheme explicitly; every policy requires an authenticated user.
• Time zones: no hard-coded zones, no DateTime.Now in database-facing layers, parsing only with explicit DateTimeStyles.
• Assistant and dialog texts are complete in all 25 languages.
• No API keys in URLs, no chat contents in logs.

The frontend has its own guard specs (layer direction, one class or interface per file, license header) and strict ESLint rules (no any, no console.log, no time-zone-unsafe date handling).

To be honest: the migration is not complete. The backend lists 9 known exceptions to the layer direction, the frontend 55 legacy files (presentation calling infrastructure directly). Both lists can only shrink: a new violation fails the tests, and a fixed entry has to come off the list. There are no exceptions for file size or one type per file.

Backend

Size: about 6,400 C# files with just over 400,000 lines (excluding migrations) and 130 controllers.

MCP interface

Klacks speaks the Model Context Protocol: POST /mcp on the official C# SDK (ModelContextProtocol.AspNetCore 2.2.0), streamable HTTP, stateless. External AI clients sign in with a JWT or a personal access token (32 random bytes, only the SHA-256 hash is stored); an OAuth authorization server with a metadata endpoint is included. Rights over MCP are capped at supervisor level.

Database

• PostgreSQL 17 (image pgvector/pgvector:pg17) with the vector and pg_trgm extensions.
• Code-first with EF Core: 166 migrations, applied automatically at startup.
• 768-dimension vectors with HNSW indexes; vector queries in plain SQL.
• Stored SQL functions serve the hot read paths of the schedule.

AI assistant Klacksy

• Providers: OpenAI, Anthropic, Google Gemini, Azure OpenAI, Mistral and DeepSeek with dedicated implementations, plus any OpenAI-compatible endpoint. The operator decides which model is used.
• Skills: 503 core skills (function calling) plus plugin skills, defined in a seed file and managed in the database. Per turn, a semantic search picks up to 20 matching skills.
• Tool loop: at most 6 iterations per turn; side-effecting calls are not repeated within the same turn.
• Local, not cloud: embeddings with multilingual-e5-base (ONNX, fp16) and reranking with the mMiniLMv2 cross-encoder (ONNX, int8) run on your own server. Model files are pinned by SHA-256.
• Memory: hybrid search combining pgvector similarity and PostgreSQL full-text search.
• Streaming: answers arrive as server-sent events.

Frontend

Size: about 2,700 TypeScript files (just under 200,000 lines) and 625 spec files.

Languages

25 languages: German, English, French and Italian are built in, 21 more come as language packs (UI, help, assistant texts, synonyms, calendar rules). Arabic and Hebrew run right to left, including PDF reports.

Scheduling engines

• TokenEvolution: genetic algorithm with tournament selection, crossover, weighted mutations, elitism and a fairness gate.
• Harmonizer / Wizard 4: genetic algorithm over a schedule bitmap, running in the background as an anytime optimizer.
• ScheduleRecovery: deterministic repair core for absences. With no I/O, clock or randomness, it returns the smallest change to the plan.

Speech input

Deepgram, Groq Whisper, AssemblyAI or your own OpenAI-compatible service; also a self-hosted faster-whisper container and Whisper directly in the browser (transformers.js on WebAssembly). A local engine based on NVIDIA Parakeet is in development and not yet part of a release.

Operations and updates

• Docker images for API, UI and updater; nginx as reverse proxy.
• On-premises bundle with Docker Compose, or a Windows installer (Inno Setup) with its own PostgreSQL instance as a Windows service.
• Auto-updates through Klacks.Updater (.NET worker). The release manifest is signed with RSA-SHA256; unsigned or tampered updates are rejected.
• A release is always the same version tag on backend and frontend, set only by script.

Tests and CI

• Backend: NUnit 4, NSubstitute, Shouldly; more than 2,300 unit test files, plus integration tests against PostgreSQL with pgvector.
• End to end: Playwright 1.61.
• CI/CD on GitHub Actions with CodeQL analysis.

This website

Blazor Server on .NET 10 (prerendered), Tailwind CSS 3.4.19, no cookies, no third parties.

License and source code

Klacks is licensed under the GNU AGPL-3.0-only. Every source file carries an SPDX header, and a test checks it. The code is on GitHub.