Skip to content

Home

Jump to bottom
Valerio edited this page Apr 21, 2026 · 5 revisions

Harpyx Wiki

Harpyx logo

Welcome. This wiki is the canonical source of developer and operator documentation for Harpyx. For a high-level overview of what Harpyx is and why it exists, see the project README.

The pages below are designed to be read in the order listed when onboarding a new contributor, and as independent references afterwards.

Understanding the system

  1. Architecture - the clean-architecture split, the WebApp/Worker services, and the end-to-end flow of a document.
  2. Configuration - how appsettings.json, environment variables, and Azure Key Vault compose into the runtime configuration of each service.
  3. Authentication and Authorization - OIDC with Microsoft Entra ID, Google OAuth, the allowlist + role model, and API keys.
  4. Resources and Localization - how Razor Pages use .resx resources, page-local Localizer, shared SharedLocalizer, and semantic keys.

Core subsystems

  1. RAG Pipeline - how a document goes from upload to a searchable, LLM-answerable chunk in the index.
  2. Jobs and Messaging - the RabbitMQ-backed asynchronous job system and how the Worker processes it.
  3. Storage and Persistence - SQL Server schema, MinIO buckets, Redis usage, and the OpenSearch chunk index.
  4. Security - malware scanning, encryption at rest, upload policies, audit events, secret handling.
  5. Observability - OpenTelemetry tracing and metrics, Serilog logging, health checks.

Building and running

  1. Development - prerequisites, building, running tests, applying EF Core migrations.
  2. Deployment - Docker Compose topology, container images, scaling considerations.
  3. CI/CD - GitHub Actions pipeline, production Ubuntu server setup, Nginx + TLS, and step-by-step deployment guide.
  4. AI Policy - our general stance on AI-assisted development, what must remain human-led, and which contributions will be rejected.

Clone this wiki locally