# 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 - Per-user lesson completion tracking - 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 - 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 and marks them complete 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 | App database | | Sessions | App backend | | Cached index metadata | App database | ## 7. Information Architecture ### Public Sections - Home - Courses - Posts - Discussions - Events ### Authenticated Capabilities - Mark lesson complete - 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//` Each post folder contains: - exactly one markdown file - optional images, downloads, or other supporting assets ### 9.2 Course / Lesson Repos Lessons live under: - `/lessons///` 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 The app should track lesson progress per signed-in user. 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 - 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.