KStack Devs — Project Brief

01 · Product

A deliberately focused first release.

V1 is a high-quality video catalog and watching experience, not a full learning-management system. This keeps the launch coherent while leaving clean extension points for text, captions, progress, and other learning features later.

01

Course

Exactly one long-form video, with its own public landing and watch page.

Single video

02

Series

Two or more ordered lessons with stable shareable lesson URLs and a persistent playlist.

Bootcamp

03

Public access

Students browse and watch without an account. Only administrative work requires KStacks login.

Free

04

Editorial control

Owners and Editors curate content, media, instructors, topics, levels, covers, and publication.

Dashboard

Not included in V1.

Student progress, enrollment, quizzes, certificates, ratings, comments, payments, captions, text-only lessons, and AI-generated articles are intentionally deferred.

02 · Decision snapshot

What the team can rely on.

Service shapeStandalone frontend + Spring service behind the existing gateway

IdentityExisting KStacks SSO; Devs-owned Owner and Editor roles

LocalesArabic and English UI with optional metadata translations

VideoMux delivery/analytics + permanent private R2 originals

TelegramOne-time resumable import from multiple authorized channels

PublishingDraft → Published → Archived; no scheduling

DiscoverySearch + type, topic, language, and managed-level filters

Featured railManual order; hidden until four published featured items exist

Launch downloadsStreaming-only safe default while alternatives remain under review

03 · Experience

Simple for students, powerful for editors.

Public journey

Hero and reviewed bilingual message about completely free practical learning
Accessible, non-autoplaying featured rail shown only at four or more items
Latest content grid and combined URL-shareable catalog filters
Course detail with one player; Series overview with ordered lessons
Dedicated lesson route, persistent playlist, and next-lesson prompt
Required custom cover, instructor profiles, topics, level, language, and Markdown description
Light/dark themes, mobile-first layouts, Arabic RTL, SEO and social metadata

Admin journey

Candidate authenticates once; Owner grants a verified known identity a role
Dashboard summarizes content, processing failures, views, and watched minutes
Direct-to-R2 video upload with visible Mux processing status and retry path
Course/Series editor, sanitized Markdown preview, translations, and lesson ordering
Reusable instructors, localized topics and levels, custom covers, and feature ordering
Editors publish/archive; Owners manage team and perform confirmed safe deletion
Every material mutation records a useful, non-secret audit event

04 · Architecture

Fits KStacks without duplicating it.

Devs follows the organization’s React/TanStack frontend and Spring/PostgreSQL service pattern. It reuses central identity and routing while owning its catalog, workflow, and roles.

BrowserSSR public pages, admin UI, Mux Player, direct presigned uploads

KStacks Gateway/devs/**, access-cookie validation, routing, rate-limit boundary

Devs ServiceCatalog, RBAC, workflow, upload coordination, provider adapters, webhooks, metrics

PostgreSQLContent, translations, taxonomy, admins, audit, import provenance, cached metrics

Media providersPrivate R2 masters and images · Mux ingest, signed playback, player analytics

Portability rule.

KStacks media IDs remain independent of provider IDs. Backend and frontend adapters isolate Mux details, and retained R2 masters support bulk re-ingest plus temporary dual-provider migration.

05 · Video & storage

Mux now, options preserved.

Mux provides a low-friction pilot with encoding, adaptive playback, signed policies, webhooks, player integration, and watch-time analytics. R2 remains the permanent source of truth for original masters.

Request upload

Admin or importer receives short-lived multipart instructions from Devs.

Upload directly to R2

Video bytes bypass Spring. The private master is recorded with size and SHA-256.

Remote Mux ingest

Devs issues Mux a short-lived R2 GET URL and listens for signed, idempotent webhooks.

Publish only when ready

A Course or Series cannot publish until every assigned provider asset is ready.

Signed public playback

The public page requests a short-lived token to discourage hotlinking; analytics stay anonymous to Devs.

Provider comparison

Provider	Strengths	Trade-offs	Position
Mux	Strong API/player, signed playback, webhooks, watch-time analytics, pilot allowance	Delivery cost grows with watched minutes; free plan stores only ten videos	V1 choice
Bunny Stream	Very low storage/CDN unit pricing, resumable uploads, token security	Cost depends on GB/bitrate; cheapest network needs Saudi playback benchmarking	Growth-cost candidate
Cloudflare Stream	Simple minute-based model and Cloudflare integration	Published minute rates are materially higher for long free viewing	Operational alternative

Student download decision

Option	Benefit	Cost / risk	Plan status
Streaming only	Lowest complexity and casual redistribution exposure	No official offline access; capture still cannot be prevented	Safe V1 default
Per-item, default off	Editors enable offline access only where justified	Derivative generation, signed URLs, bandwidth, UI/support work	Recommended option to consider
Always downloadable	Best offline accessibility	Highest redistribution, storage, bandwidth, and takedown exposure	Not recommended by default

Any future download exposes a controlled derivative—never the permanent R2 master.

06 · Migration

Telegram is an input, not the video host.

A one-time, user-authorized MTProto importer scans multiple owned/licensed channels and creates private media records. It is resumable after failure but never becomes a continuous sync.

01

Inventory first

Dry-run every channel oldest-to-newest and record message ID, caption, date, filename, duration, size, and ordering hints.

02

Resume safely

SQLite ledger keys work by channel + message, records checksums and stages, skips confirmed work, and retries failures.

03

Media inbox

Upload to R2, start Mux ingest, and expose unassigned media in the admin dashboard. Never guess a Course or Series.

Security and rights.

Use KStacks’ own Telegram API ID, store the user session outside source control, issue a short-lived Devs import credential, clean temporary files after verification, and import only content KStacks may retain and publicly stream.

07 · Visual identity

The newest supplied identity leads.

The Behance screenshots define the core palette, Alexandria typography, geometric language, and Devs service mark. The existing portal informs UI ergonomics and localization—not its conflicting duplicated color tokens.

Emerald#15BB81

Light reflected#8ADDC0

Dark reflected#1A6F52

Black#0B0B0B

Grey#434242

White#FFFFFF

Documented conflict

The older repository PDF labels Poppins, while the newer supplied identity screenshots specify Alexandria. The portal CSS also duplicates token blocks with different OKLCH values.

Resolution

Use one Devs token layer, Alexandria for Arabic and Latin, the supplied exact palette, and the existing light/dark Devs SVG. Do not copy the conflicting token blocks.

Design approval gate.

Before production styling, approve a light/dark token sheet and responsive landing/catalog, watch, and admin-editor mockups—including a real Arabic RTL pass and WCAG 2.2 AA contrast/focus checks.

08 · Delivery

Five controlled phases.

Discover and approve

Inspect private deployment/CI/DNS/secrets/observability, confirm Mux/R2 accounts and budget ownership, approve visual tokens/mockups, and assign marketing/legal reviewers.

Foundations

Create frontend/service repositories, gateway/Eureka integration, schema, public API, SSO-backed Devs RBAC, audit, and fake/real provider adapters.

Public experience

Deliver bilingual themes, landing/featured/catalog, Course/Series/lesson routes, signed player, SEO, accessibility, and reviewed copy.

Admin and media

Deliver dashboard, editorial workflows, direct R2 uploads, Mux lifecycle/webhooks, covers, taxonomy, instructors, team, analytics, and safe deletion.

Migration and acceptance

Dry-run and reconcile Telegram import, complete security/RTL/mobile/visual/playback tests, approve legal text, prepare runbooks, then publish reviewed content.

Deployment default.

Use the same supported frontend platform as the portal, the same container platform as existing Spring services, and devs.kstacks.org. Phase 0 discovers the private implementation details before provisioning.

09 · Acceptance

Evidence before launch.

Product behavior

Anonymous browse/watch, 0/3/4+ featured states, URL filters, Course/Series invariants, next-lesson prompt, translation fallback, draft/archive hiding.

Admin & media

Known-candidate denial, Editor/Owner permissions, direct upload, processing failure/retry, publish validation, audit, safe delete, webhook replay/idempotency.

Quality

320–1440 px visual regression, English/Arabic × light/dark, WCAG keyboard/screen-reader pass, Core Web Vitals, SEO, Saudi playback measurements.

Security

JWT/JWKS revalidation, CSRF + Origin, rate limits, sanitized Markdown, MIME spoofing, revoked roles, scoped import token, secret/redaction checks.

Migration

Multiple channels, dry run, pagination, interrupted stages, duplicate message/checksum, temp cleanup, expired credentials, rerun idempotency, reconciliation.

Operations

Health/readiness, PostgreSQL backup restore, R2 checksum inventory, Mux/R2 outage runbooks, spend/usage alerts, admin recovery, structured logs.

10 · Launch gates

Inputs KStacks must close.

Before implementation styling

Approve the Devs token sheet and three responsive mockup families
Confirm Alexandria assets/licensing and exact Devs logo variants
Review initial Arabic and English marketing copy

Before paid provisioning

Provide infrastructure access, Mux/R2 accounts, DNS owner, and budget thresholds
Provide first-Owner identity and Telegram operator/API credentials
Confirm rights for every imported channel/video

Before production traffic

Approve privacy, terms, copyright/takedown, and analytics/cookie wording
Complete security, backup/restore, Saudi playback, accessibility, and RTL acceptance
Approve the initial content selected for publication

Decision retained for review

Streaming-only is the V1 default until downloads are explicitly selected
AI transcription/articles remain a separate measured Phase 2
Provider migration occurs only after real cost and Saudi quality data justify it

References

Free learning, built for students.

A deliberately focused first release.

Course

Series

Public access

Editorial control

What the team can rely on.

Simple for students, powerful for editors.

Public journey

Admin journey

Fits KStacks without duplicating it.

Mux now, options preserved.

Request upload

Upload directly to R2

Remote Mux ingest

Publish only when ready

Signed public playback

Provider comparison

Student download decision

Telegram is an input, not the video host.

Inventory first

Resume safely

Media inbox

The newest supplied identity leads.

Documented conflict

Resolution

Five controlled phases.

Discover and approve

Foundations

Public experience

Admin and media

Migration and acceptance

Evidence before launch.

Product behavior

Admin & media

Quality

Security

Migration

Operations

Inputs KStacks must close.

Before implementation styling

Before paid provisioning

Before production traffic

Decision retained for review

Primary technical sources.