Orkyo

---

Foundation is the feature core shared by the two Orkyo product editions. It contains no runtime wiring — no Program.cs, no DI registration, no middleware. The product repos supply the composition and the tenant/hosting adapters; foundation supplies the behaviour.

If you're here to use or self-host Orkyo, start at orkyo-community. This repo is the shared library those editions build on.

What's included

• Domain models — spaces, requests, criteria, scheduling, feedback, templates, sites, announcements
• Service interfaces — ISpaceService, IRequestService, ISchedulingService, etc.
• Repository interfaces + implementations — Postgres-backed via Npgsql
• OrgContext + IOrgContextAccessor — pluggable org identity (injected by product repos)
• Validators — FluentValidation rules for all request/command types
• Scheduler engine — constraint-based space assignment
• Shared frontend components — domain React components, hooks, pages, and routing infrastructure (see frontend/ and ARCHITECTURE.md)
• Migrations — domain schema published as Orkyo.Foundation.Migrations

How it's consumed

Foundation is published to GitHub Packages and pinned by the product repos:

• Backend — NuGet packages Orkyo.Foundation.* (Core, Web, Migrations, …)
• Frontend — npm package @kymr10n/foundation

orkyo-community and orkyo-saas pin an exact foundation version and bump it through their release pipelines when a new version is published. Neither runs foundation directly — each composes it with its own runtime wiring: Community with single-tenant adapters, SaaS with multi-tenant machinery. Package versions follow SemVer; consumer-facing changes are recorded in CHANGELOG.md.

Structure

Orkyo.Foundation.slnx   ← Solution at repo root
backend/
  shared/                 ← Orkyo.Shared (config keys, environment names)
  core/                   ← Orkyo.Foundation.Core (models, services, repositories, validators)
  src/                    ← Orkyo.Foundation.Web (endpoints, middleware, DI extension methods)
  migration-abstractions/ ← IMigrationModule, MigrationScript
  migrator-runtime/       ← the DbUp-based runner, checksum policy, advisory lock
  migrations-foundation/  ← Orkyo.Foundation.Migrations (domain schema as embedded SQL)
  seeding/                ← demo/seed data generator
  testsupport/            ← shared test helpers consumed by the product test suites
  tests/                  ← Foundation tests (unit + integration)
frontend/
  src/                    ← Shared domain components, hooks, pages, route tree
  contracts/              ← wire constants (headers, claims, error codes, roles, plans)
  docs/                   ← UI guidelines
  vitest.config.ts

Foundation-frontend intentionally has no vite.config.ts — it is a contracts + test-harness package, not a runtime app. vite is only used via vitest for the test runner.

Building

dotnet build Orkyo.Foundation.slnx
dotnet test Orkyo.Foundation.slnx

Run what CI runs before you push:

scripts/check.sh          # restore, format, build, migration lint, dead registrations, every test
scripts/check.sh --fast   # architecture and convention tests only, no database (the pre-push hook)

The full check starts a fresh Postgres container per run (orkyo-test-postgres-foundation, port 5440; CI gets a new one per run too) and points the test fixtures at it through the same CI=true + ConnectionStrings__Postgres switch the fixtures already have. Nothing else starts Testcontainers, which cannot map ports under rootless Docker. A bare dotnet test Orkyo.Foundation.slnx still works where Testcontainers does.

Placement rule

orkyo-foundation holds every behavior that applies identically to both orkyo-saas (multi-tenant hosted) and orkyo-community (single-tenant standalone). Any new code whose behavior has no Community analogue — cross-tenant admin, tenant provisioning, break-glass impersonation, service tiers, subdomain→tenant resolution — belongs in orkyo-saas instead.

See CONTRIBUTING.md for the full placement workflow and the downstream-impact checklist.

Contributing & support

Contributions follow CONTRIBUTING.md and the Code of Conduct. Questions → Discussions; bugs → Issues; vulnerabilities → SECURITY.md; help routing → SUPPORT.md.

License

GNU Affero General Public License v3.0 — same licence as the Community edition it powers.