Initial Robot U site prototype
This commit is contained in:
commit
fe19f200d7
27 changed files with 3677 additions and 0 deletions
470
docs/community-platform-design-doc.md
Normal file
470
docs/community-platform-design-doc.md
Normal file
|
|
@ -0,0 +1,470 @@
|
|||
# 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/<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
|
||||
|
||||
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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue