LearnStack

LearnStack is a white-label platform for multi-branch education businesses that teach live — not a single LMS, and not an education product of its own. It is an education-aware CMS, learning engine, and platform foundation that powers different brands, landing pages, catalogs, and learner portals. The same code paths serve a language school, a yoga studio, a music school, or a coding bootcamp — the difference between them is tenant customization data loaded at provisioning, not compiled code (ADR-0018).

That claim has a stated edge: content shape, presentation and pure rule evaluation are tenant data; stateful entitlement and external capability invocation are platform features gated by plan. See Platform Vision § Genericity boundary.

Two tenants in unrelated domains exist from Phase 02a Packet 7 onward and are both rendered in a browser in Phase 02d, so genericity is tested continuously rather than asserted and checked once at the end.

LearnStack ships in three production deployment modes — SaaS, Dedicated, Self-Hosted — backed by the companion LearnStack Hub repository, which provides the SaaS / Dedicated control plane, plan editor, custom-domain admin, and license-key issuance.

Today only Development and SaaS are wired and tested end to end. Dedicated and the two Self-Hosted DeploymentMode values (SelfHostedOnline, SelfHostedAirGapped) are prepared seams, not supported deployments — the composition root branches on them, but their adapters and integration suites land in Phase 11 per ADR-0035. See 25-deployment-models.md for what a prepared seam means concretely.

The Hub repo is expected to live at ../LearnStack-Hub (sibling to this repo on the developer's workstation) so the cross-repo doc links resolve. The Hub repository owns its own roadmap at ../LearnStack-Hub/docs/roadmap/. See LearnStack-Hub on GitHub and docs/roadmap/phase-02c-hub-foundation.md for LearnStack's side of the boundary.

Status

Phase 01 complete. Phase 02a in progress — packets 0–3 shipped; packets 3b–10 re-scoped on 2026-08-08.

Phase 01 shipped the .NET 10 solution scaffold, the pnpm frontend monorepo (apps/web + packages/{config,ui,sdk}), the local-dev docker-compose stack, and the DX + CI surround. See phase-01-repository-tooling.md for the per-packet history.

Phase 02a packets 0–3 shipped the foundation decisions (ADR-0023 Vogen, ADR-0024 API versioning, ADR-0028 audit partition management — whose timing later moved to Phase 11), the shared kernel core, and the ADR-0032 cross-cutting foundation.

The 2026-08-08 restructure moved correctness earlier (the corrected RLS template in ADR-0003 Amendment 3, durable MUST-class audit in ADR-0033), moved additive infrastructure later behind its ports (ADR-0035), and moved the genericity proof earlier — two seed tenants in Packet 7, rendered in a browser in Phase 02d, the next user-visible milestone. Module assemblies hold no domain code yet.

make install   # one-time: deps + git hooks
make dev       # bring local stack up
make seed      # verify health + print demo credentials

make seed's health gate currently times out, because three compose services declare no healthcheck. Phase 02a Packet 3b fixes it along with the rest of the Phase 01 development-loop debt.

Direction At A Glance

• Backend: .NET 10, ASP.NET Core, Entity Framework Core, MediatR.
• Database: PostgreSQL 18, with Row-Level Security from day one. Tenant + Organization defense in depth (ADR-0003 Amendment 1 for organization scope, Amendment 3 for the corrected policy template and the four-role database model, ADR-0017). The canonical SQL lives in exactly one file: Database Standards.
• Foundation ports: IEventBus, ICacheService, ISecretProvider, IEntitlementProvider, IHostToTenantResolver in LearnStack.SharedKernel, each with a working default implementation. Vendor adapters — Dapr (ADR-0014), Kafka, Valkey (ADR-0030), Vault, APISIX (ADR-0015) — are demand-gated: each has an owning phase and a written trigger condition in ADR-0035.
• Object storage: SeaweedFS locally, S3-compatible storage in production.
• Search: PostgreSQL full-text search first; Meilisearch behind ITenantSearch when quality or scale requires it.
• Frontend: Next.js 15 (App Router), TypeScript, React. One application (apps/web) with route segments for public, studio, and portal; a multi-app split inside this repo is not planned before Phase 11. The operator portal (frontend/apps/operator-portal) lives in the separate LearnStack-Hub repository.
• Identity: Self-hosted Keycloak with two realms — learnstack for tenant users, learnstack-hub for operators.
• Architecture: Modular monolith with explicit module contracts.
• Tenant customization: Per ADR-0018, content types, page blocks, lesson item types, level taxonomies, scoring rules, completion rules, custom fields, and notification templates are data authored by tenants, not code. The core stays generic, within the boundary the ADR's 2026-08-08 amendment draws.
• Audit: Append-only LearnStack.Modules.Audit with EF interceptor + MediatR behavior. MUST-class audit is a durable intent written inside the business transaction per ADR-0033, which supersedes ADR-0016; audit_log partitioning and retention land in Phase 11.
• Entitlements: Feature-based projection mirrored from the Hub per ADR-0021; typed FeatureKeys / LimitKeys registries. The Hub contract is governed by two invariants — the Hub stores no tenant content, and every crossing goes through a named adapter — per ADR-0034.
• Live classroom: In-app WebRTC; self-hosted LiveKit OSS is the default; LiveKit Cloud available behind the same ILiveClassProvider interface. A custom WebRTC SFU is explicitly out of scope.
• Recording: Supported via LiveKit Egress to S3/SeaweedFS; tenant-configurable; consent-aware; off by default.
• Deployment: Triple deployment model per ADR-0020 — SaaS / Dedicated (Hub-backed) and Self-Hosted (RSA-signed .lic file + optional phone-home + 30-day grace).

Documentation Map

Architecture (docs/architecture/)

Strategy & shape:

• 01 — Platform Vision
• 02 — Domain Model
• 03 — Module Boundaries
• 04 — Technical Architecture
• 05 — MVP Scope
• 06 — Extension Model

Live classroom:

• 07 — In-App Live Classroom
• 08 — Live Classroom Cost Model

Platform concerns:

• 09 — Tenant Isolation
• 10 — Cross-Module Contracts
• 12 — Localization
• 13 — Identity and Authentication
• 14 — Frontend Architecture
• 15 — Events and Outbox
• 16 — Media Pipeline
• 17 — Page Builder
• 20 — Search
• 21 — Feature Flags & Entitlements
• 23 — Data Protection (KVKK / GDPR)

LearnStack Hub + deployment:

• 24 — LearnStack Hub
• 25 — Deployment Models
• 26 — Hybrid License Model
• 27 — Custom Domain + TLS

Platform substrate deep dives:

• 28 — Platform Tenant + Organization
• 29 — Dapr Integration
• 30 — API Gateway (APISIX)
• 31 — Audit Subsystem
• 32 — Tenant Customization Model
• 33 — Cross-Cutting Concerns

Decision context:

• 18 — WebRTC Build vs Adopt
• 19 — MVP Vertical Slice

Decisions (docs/decisions/)

• ADR index — accepted decisions with their reasoning and consequences. The 2026-05-18 redesign added ADRs 0014–0022; the 2026-08-08 restructure added ADR-0033 (audit durability, supersedes ADR-0016), ADR-0034 (Hub contract invariants) and ADR-0035 (demand-gated infrastructure).

Engineering Standards (docs/standards/)

• Standards index — rules that apply to every PR: coding, testing, security, observability, accessibility, performance, infrastructure-stack rules, and the architecture-test catalogue.

Roadmap (docs/roadmap/)

• Phased roadmap — phases 00 through 12, including Phase 02d (Two-Tenant Walking Skeleton) and the Phase 02c (Hub Integration) and Phase 09b (Hub Billing) parallel tracks. The dependency map there is authoritative for order; filename order is not.

Reference

• Glossary — canonical definitions.

Conventions

• All documentation is written in English (see ADR-0007).
• Diagrams use Mermaid in fenced code blocks.
• Architectural decisions are recorded as ADRs under docs/decisions/.
• Engineering rules live under docs/standards/.
• Each piece of knowledge lives in exactly one place; the glossary is the single source of truth for terminology.

How To Read This Repository

For the strategy and the headline decisions:

1. Platform Vision
2. MVP Scope
3. Roadmap overview
4. Phase 02a: Kernel + Tenancy — where the work is now
5. Phase 02d: Two-Tenant Walking Skeleton — where it is going next
6. ADR index

For the technical foundations:

1. Technical Architecture
2. Module Boundaries
3. Tenant Isolation
4. Cross-Module Contracts
5. Tenant Customization Model
6. Infrastructure Stack Standards
7. Engineering principles

For the Hub + deployment story:

1. LearnStack Hub
2. Deployment Models
3. Hybrid License Model
4. Phase 02c: Hub Foundation

For the live classroom direction:

1. In-App Live Classroom
2. Live Classroom Cost Model
3. WebRTC Build vs Adopt
4. ADR-0005: Live Classroom Media Stack