470 lines
13 KiB
Markdown
470 lines
13 KiB
Markdown
# 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.
|