Robot-U/robot-u-site
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
robot-u-site/docs/community-platform-design-doc.md

13 KiB
Raw Blame History

Community Learning Platform Design Doc

Status: Draft 0.2 Date: 2026-04-07 Owner: Product / Founding Team

1. Summary

This project is a web application for a small robotics-focused community that mixes structured learning with community participation. Members should be able to read lessons, share technical content, discuss blockers, and track progress through a course, while all core community content remains first-class data in Forgejo.

The app is intentionally not the source of truth for content. Instead, it acts as:

  • a polished public frontend
  • a better reading and discovery experience
  • a better discussion experience
  • a progress-tracking layer
  • an integration layer over Forgejo and calendar feeds

If the custom frontend disappeared, the core community content should still exist in Forgejo.

2. Product Goals

Primary Goals

  • Teach members through bite-sized lessons that build toward larger projects
  • Make it easy to browse courses, posts, and related resources
  • Give members a place to discuss projects, blockers, and ideas
  • Keep the publishing and discussion model aligned with Forgejo
  • Provide a strong public landing page for discovery

Secondary Goals

  • Support both official org-authored content and user-authored public content
  • Aggregate upcoming community events
  • Track per-user lesson completion

3. Product Principles

Forgejo-First

Forgejo is the system of record for:

  • identity
  • content repositories
  • issue-backed discussions
  • team-based permissions

Frontend-First Experience

This app should provide a much better user experience than the raw Forgejo UI for:

  • reading courses
  • browsing posts
  • finding discussions
  • seeing upcoming events

Public By Default

Reading should not require an account. Authentication is required for participation.

Minimal App-Owned Data

The app should own only the state that does not naturally belong in Forgejo, such as:

  • login/session state
  • lesson completion state
  • cached indexing metadata
  • app configuration

4. MVP Scope

Included

  • Public landing page
  • Public course browsing
  • Public post browsing
  • Public discussion reading
  • Public event calendar
  • Forgejo-only sign-in
  • Auto-discovery of eligible public repos
  • Rendering markdown content from Forgejo repos
  • Discussion creation and replies from this app, backed by Forgejo issues/comments
  • Team-derived admin/moderator permissions
  • Webhook-driven sync from Forgejo
  • SSE updates for open sessions when content/discussions change

Excluded

  • In-browser editing of posts or lessons
  • In-browser media uploads
  • Non-Forgejo authentication providers
  • Search
  • Rich public profiles
  • Per-user lesson completion tracking
  • Private repo indexing
  • Admin-created calendar events in this app
  • Review or approval workflow before publishing

5. Core User Experience

New Visitor

  1. Lands on homepage
  2. Understands the community mission quickly
  3. Sees featured courses, recent posts, upcoming events, and recent discussions
  4. Opens a course, post, or discussion without signing in

Signed-In Member

  1. Signs in with Forgejo
  2. Reads lessons
  3. Creates general discussion threads
  4. Creates post- or lesson-linked discussion threads from content pages
  5. Replies, edits, and otherwise interacts through the app UI

Content Author

  1. Creates or edits content directly in Forgejo
  2. Pushes changes to a public repo
  3. The app reindexes the repo via webhook
  4. Updated content appears in the frontend

6. Source of Truth Matrix

Concern System of Record
User identity Forgejo
Authentication Forgejo OAuth/OIDC
Roles / moderation authority Forgejo org/team membership
Courses / lessons / blog content Forgejo repos
Content assets / downloads Forgejo repos
Discussions / comments Forgejo issues and issue comments
Events External ICS feeds
Lesson progress Post-MVP app database
Sessions App backend
Cached index metadata App database

7. Information Architecture

Public Sections

  • Home
  • Courses
  • Posts
  • Discussions
  • Events

Authenticated Capabilities

  • Create discussion threads
  • Reply to discussions
  • Edit supported discussion content through the app

Post-MVP Sections

  • Profiles
  • Search
  • Rich dashboards

8. Content and Repo Model

8.1 Repo Discovery Rules

The app should automatically discover content from:

  • all public repos on the configured Forgejo instance
  • org-owned repos
  • user-owned repos

The app should exclude:

  • forks
  • repos without recognized content folders
  • private repos

8.2 Repo Classification Rules

A repo is considered content-bearing if it contains one or both of:

  • /blogs/
  • /lessons/

Interpretation:

  • repos with /lessons/ are course repos
  • repos with /blogs/ are blog/project repos
  • a single repo may contain both and therefore appear in both the course and post experiences

8.3 Ownership Expectations

  • Official lesson plans and course content will usually live in org repos
  • Users may publish content through their own public repos
  • User repos should be auto-discovered if they match the folder conventions

9. Content Folder Conventions

9.1 Blog / Post Repos

Posts live under:

  • /blogs/<post-folder>/

Each post folder contains:

  • exactly one markdown file
  • optional images, downloads, or other supporting assets

9.2 Course / Lesson Repos

Lessons live under:

  • /lessons/<chapter-folder>/<lesson-folder>/

Each lesson folder contains:

  • exactly one markdown file
  • optional supporting assets or downloadable materials

This structure supports chapters while keeping lesson resources colocated with the lesson content.

9.3 File Naming Rules

  • The markdown filename may be any name
  • The app should treat the single markdown file in the folder as the primary content file
  • Frontmatter title should be used when present
  • The filename should be the fallback title when frontmatter title is missing

9.4 Frontmatter

Markdown files should support frontmatter. Initial expected fields:

  • title
  • summary
  • date
  • tags
  • order

Additional lesson-specific fields will likely be needed, but the exact schema still needs review.

10. Course Model

Course Definition

  • A course is represented by a repo
  • Multiple courses must be supported from day one
  • Courses should be presented as linear learning experiences, but users may enter any lesson directly

Chapter and Lesson Structure

  • Chapters are inferred from the folder structure under /lessons/
  • Lessons are individual markdown-backed units with colocated assets
  • Lesson order should be linear within a chapter
  • The UI should provide clear previous/next navigation while still allowing free access

11. Posts and Lessons

The product will use one publishing system for markdown content, but the app should expose distinct user experiences:

  • Courses for structured lesson content
  • Posts for general blog/project content

In practice:

  • lessons are a flavor of posts
  • the difference comes from repo structure and organization, not a separate authoring tool

Publishing model:

  • public repo content appears automatically
  • no review gate or approval step in MVP
  • content authoring and updates happen in Forgejo, not in this app

12. Discussion Model

12.1 General Principle

The site should provide its own frontend for discussions, but the underlying records must be Forgejo issues and comments.

12.2 General Discussions

General discussion threads should live in a dedicated org-level discussions repo.

12.3 Content-Linked Discussions

Post- and lesson-linked discussions should live in the same repo as the content they discuss.

Requirements:

  • multiple discussion threads may be linked to the same repo
  • multiple discussion threads may be linked to the same lesson or post
  • manually created Forgejo issues should appear in the app if they include the expected content link

12.4 Linking Convention

The app should detect that an issue belongs to a specific post or lesson by parsing links contained in the issue body.

Recommended MVP behavior:

  • support canonical app URLs to posts/lessons
  • support Forgejo file or content URLs when feasible

This keeps linkage issue-driven rather than requiring authors to update post frontmatter with discussion IDs.

12.5 Write Permissions

Any signed-in user with a Forgejo account should be able to:

  • create general discussion threads
  • create post-linked or lesson-linked discussion threads
  • reply to discussions
  • edit their discussion content to the extent supported by Forgejo

Because Forgejo remains accessible directly, the app should mirror the practical capabilities available through Forgejo where possible.

13. Authentication and Authorization

Authentication

  • Forgejo is the only authentication provider for MVP
  • Users sign in using Forgejo OAuth/OIDC
  • The app creates its own local authenticated session after login

Session Model

Recommended MVP implementation:

  • app session stored in a secure HttpOnly cookie
  • Forgejo access token stored encrypted server-side
  • frontend JavaScript never directly receives the raw Forgejo token

Authorization

App roles should be derived from Forgejo org/team membership rather than maintained separately in this app.

Expected role mapping:

  • member
  • moderator
  • admin

Exact team-to-role mapping should be configured in app settings.

14. Calendar Model

The event calendar should be read-only in MVP.

Requirements:

  • support one or more ICS feed URLs
  • display upcoming events publicly
  • surface upcoming events on the homepage

Non-goal for MVP:

  • creating or editing events in the app

Events should continue to be managed in external calendar tools.

15. Progress Tracking

Lesson progress is no longer part of the MVP.

Post-MVP state model:

  • not started
  • completed

Storage:

  • progress should live in the app database, not in Forgejo

Reason:

  • this is app-specific state
  • it is easier to query and render
  • it avoids polluting content repos with user interaction data

16. Landing Page

The homepage should prioritize:

  • featured courses
  • recent posts
  • upcoming events
  • recent discussions

The page should clearly communicate that this is:

  • a technical learning space
  • a community space
  • a place to follow structured project-building content

17. Recommended Technical Direction

The exact stack is still open, but the current recommendation is:

  • Next.js for the frontend and server layer
  • PostgreSQL for app state and indexing metadata
  • background jobs for indexing and webhook processing
  • markdown rendering pipeline for repo content
  • SSE for live updates to connected clients

Additional integration needs:

  • Forgejo API client
  • webhook receiver for repo and issue changes
  • ICS feed ingestion

18. Sync Model

Primary sync mechanism:

  • Forgejo webhooks

Expected webhook-driven updates:

  • repo content changes
  • issue changes
  • issue comment changes

Realtime UX:

  • the app should push relevant updates to open sessions using SSE

Recommended safety net:

  • periodic reconciliation job to recover from missed webhook deliveries

19. MVP Non-Goals

The following are explicitly out of scope for MVP:

  • browser-based content editing
  • browser-based asset uploads
  • search
  • rich user profiles
  • per-user lesson completion tracking
  • non-Forgejo auth providers
  • private repo support
  • complex moderation workflows
  • custom event authoring

20. Risks

  • Forgejo OAuth tokens may be broader in power than ideal for third-party app writes
  • Auto-discovering all public repos on the instance may create indexing and relevance challenges
  • Content conventions need to be strict enough to keep rendering predictable
  • Issue-to-content linking needs a clear convention so manually created issues are detected reliably
  • Team-based permissions require stable org/team structure in Forgejo

21. Open Questions For Review

These are the main questions still worth reviewing before implementation starts:

  1. What is the exact frontmatter schema for posts vs lessons?
  2. How should chapter ordering be defined: folder naming, frontmatter, or both?
  3. What exact issue-body link formats should count as a post/lesson association?
  4. What is the moderator toolkit needed on day one?
  5. How should featured courses/posts be chosen for the homepage?
  6. Which Forgejo teams should map to moderator and admin?
  7. How should multiple ICS feeds be labeled and grouped in the UI?
  8. Do we want a dedicated course metadata file later, or is repo/folder inference enough?

22. Immediate Next Steps

  1. Review this draft and resolve the open questions in Section 21.
  2. Define the exact repo conventions and frontmatter schema.
  3. Define the Forgejo integration contract for auth, repo indexing, and issue-backed discussions.
  4. Create wireframes for home, courses, posts, discussions, and events.
  5. Choose the implementation stack and start the technical design.