159 lines
8.3 KiB
Markdown
159 lines
8.3 KiB
Markdown
# Fargo 3D Community Content & Repository Hub Architecture (v5)
|
|
|
|
This document outlines the architecture, API schemas, configuration, and implementation plan for upgrading the **Fargo 3D Wiki, Challenges, & Community Resources** system to consume markdown and structured assets directly from the **primary Git repository** (`Fargo3d/3DPrintMeetup`) instead of the flat Gitea Wiki API.
|
|
|
|
---
|
|
|
|
## 1. Overview & Key Advantages
|
|
|
|
Rather than relying on the legacy Gitea Wiki API (which enforces a flat page hierarchy and requires an $O(N)$ loop to base64-decode each page just to read tags), the website will connect to the **Gitea Repository REST API**.
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────────────────────────────┐
|
|
│ COMMUNITY RESOURCE HUBS (WEBSITE) │
|
|
├─────────────────────────┬─────────────────────────────┬────────────────────────────────┤
|
|
│ 🏆 Challenges Hub │ 🛠️ Tools & Gear Hub │ 📚 Wiki Knowledge Base │
|
|
│ Route: `/challenges` │ Route: `/tools` │ Route: `/wiki?page={Path}` │
|
|
│ • Active Challenges │ • 3D Fuel Partner Perk │ • Meetup Info & Dates │
|
|
│ • Past Archive │ • Curated Tools & Reviews │ • Hardware & Slicer Guides │
|
|
│ • Direct STL / Files │ • HueForge Color Palette │ • Announcements Archive │
|
|
└─────────────────────────┴─────────────────────────────┴────────────────────────────────┘
|
|
▲ ▲
|
|
│ │
|
|
┌──────────────────────────────┴───────────────────────────────┴─────────────────────────┐
|
|
│ GITEA REPOSITORY REST API (BRANCH-AWARE) │
|
|
│ Swagger: https://meetup.fargo3d.com/api/swagger │
|
|
│ • Git Tree (Recursive): `/api/v1/repos/{owner}/{repo}/git/trees/{branch}?recursive=1` │
|
|
│ • Raw Markdown: `/api/v1/repos/{owner}/{repo}/raw/{filepath}?ref={branch}` │
|
|
│ • Raw JSON / Assets: `/api/v1/repos/{owner}/{repo}/raw/HueForge/3d-Fuel.json` │
|
|
└────────────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Major Advantages:
|
|
1. **Branch & Fork Isolation for Safe Local Testing**:
|
|
- The repository owner, repository name, and branch/ref are configurable via `appsettings.json`.
|
|
- Developers can point their local environment to a fork (e.g. `espoon/3DPrintMeetup`) or a test branch (e.g. `v5-content`) and test website rendering immediately without altering production markdown or touching the live wiki.
|
|
2. **Instant $O(1)$ Tree Discovery (Zero N+1 Calls)**:
|
|
- A single recursive git tree request retrieves all markdown files, folder hierarchies, sizes, and git commit SHAs in ~60ms.
|
|
3. **True Folder Hierarchy & Categories**:
|
|
- Files are organized into natural repository directories (`challenges/`, `announcements/`, `HueForge/`, `tools/`) rather than flat wiki slug naming.
|
|
4. **Structured Asset Ingestion**:
|
|
- Directly loads `HueForge/3d-Fuel.json` to provide real-time filament hex color palettes, transmissivity values, and filament profiles on `/tools`.
|
|
5. **Direct Raw Streaming**:
|
|
- The raw API streams pure UTF-8 markdown text directly without base64 wrapper overhead.
|
|
|
|
---
|
|
|
|
## 2. Configuration & Branch-Targeting Schema
|
|
|
|
In `Fargo3D.Web/appsettings.json`:
|
|
|
|
```json
|
|
{
|
|
"CommunityContent": {
|
|
"GiteaBaseUrl": "https://meetup.fargo3d.com",
|
|
"Owner": "Fargo3d",
|
|
"Repo": "3DPrintMeetup",
|
|
"Branch": "master",
|
|
"CacheDurationMinutes": 15
|
|
}
|
|
}
|
|
```
|
|
|
|
In `Fargo3D.Web/appsettings.Development.json` (for local dev against a fork or branch):
|
|
|
|
```json
|
|
{
|
|
"CommunityContent": {
|
|
"Owner": "espoon",
|
|
"Repo": "3DPrintMeetup",
|
|
"Branch": "dev"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Gitea API Endpoints Utilized
|
|
|
|
| Operation | Gitea Endpoint | Description |
|
|
| :--- | :--- | :--- |
|
|
| **Recursive Tree** | `GET /api/v1/repos/{owner}/{repo}/git/trees/{branch}?recursive=1` | Returns the entire file tree. Filter for `item.path.EndsWith(".md")` to index all content in 1 call. |
|
|
| **Raw Content** | `GET /api/v1/repos/{owner}/{repo}/raw/{filepath}?ref={branch}` | Streams the raw markdown or JSON file content. |
|
|
| **File Metadata** | `GET /api/v1/repos/{owner}/{repo}/contents/{filepath}?ref={branch}` | Returns metadata, commit info, and file size. |
|
|
|
|
---
|
|
|
|
## 4. Repository Folder Taxonomy & Routing
|
|
|
|
The files in `Fargo3d/3DPrintMeetup` map to website sections as follows:
|
|
|
|
| Repository Directory / File | Category | Target Route / UI Component |
|
|
| :--- | :--- | :--- |
|
|
| `challenges/*/readme.md`, `challenges.md` | `challenges` | `/challenges` & `/wiki?path=challenges/...` |
|
|
| `tools/*.md`, `Supporting-Our-Community.md` | `tools` | `/tools` & `/wiki?path=tools/...` |
|
|
| `HueForge/README.md`, `HueForge/3d-Fuel.json` | `hueforge` | `/tools` & `/wiki?path=HueForge/...` |
|
|
| `announcements/*.md` | `announcements` | `/wiki?path=announcements/...` |
|
|
| `Readme.md`, `itinerary.md`, `ideas.md` | `meetup` | `/wiki?path=Readme.md` (Home) |
|
|
|
|
---
|
|
|
|
## 5. Frontmatter YAML Schema Standard
|
|
|
|
Markdown files can optionally define frontmatter for card titles, badges, and sorting:
|
|
|
|
```yaml
|
|
---
|
|
title: "September 2026: Practi-FALL Prints"
|
|
category: "challenges"
|
|
subcategory: "2026"
|
|
order: 1
|
|
description: "Functional utility and everyday practicality challenge."
|
|
tags:
|
|
- active
|
|
- functional
|
|
- contest
|
|
---
|
|
```
|
|
|
|
If frontmatter is omitted, the title defaults to the filename (or first `# H1` header), and the category defaults to the parent folder name.
|
|
|
|
---
|
|
|
|
## 6. Implementation Architecture
|
|
|
|
### 1. New Content Service: `CommunityRepoService.cs`
|
|
Replaces legacy `wikiAPI` in `SharedClasses/`:
|
|
- **`GetContentTreeAsync()`**: Fetches and caches the recursive git tree for `{Owner}/{Repo}@{Branch}`.
|
|
- **`GetRawFileAsync(string path)`**: Downloads raw markdown text using `?ref={Branch}`.
|
|
- **`GetFilamentDatabaseAsync()`**: Downloads and deserializes `HueForge/3d-Fuel.json`.
|
|
- **`ParseFrontmatter(string markdown)`**: Extracts metadata (`title`, `category`, `order`, `tags`) using `FrontmatterParser.cs`.
|
|
|
|
### 2. Dedicated Hub: `Fargo3D.Web/Components/Pages/Tools.razor`
|
|
- **Route**: `@page "/tools"`
|
|
- **Partner Voucher Card**: 3D Fuel voucher with one-click code copy and direct tracking link.
|
|
- **Interactive HueForge Palette**: Visual swatch grid populated directly from `HueForge/3d-Fuel.json`.
|
|
- **Community Supplies**: Community-tested recommendations pulled directly from the repo's tools markdown.
|
|
|
|
### 3. Categorized Wiki Tree: `WikiPage.razor`
|
|
- Replaces flat list with folder-aware accordion sidebar:
|
|
- 📅 **Meetup & Schedule** (`Readme.md`, `itinerary.md`, `ideas.md`)
|
|
- 🏆 **Maker Challenges** (Grouped by year/month)
|
|
- 🛠️ **Tools & Hardware** (Supplies, recommendations)
|
|
- 🎨 **HueForge Guides** (Filament guides, color theory)
|
|
- 📢 **Announcements Archive**
|
|
|
|
---
|
|
|
|
## 7. Migration & Local Testing Workflow
|
|
|
|
1. **Create Branch or Fork**:
|
|
- In `meetup.fargo3d.com`, create a branch (e.g. `v5-content`) or fork `3DPrintMeetup` to your user account.
|
|
2. **Update Local Config**:
|
|
- Set `"Branch": "v5-content"` in `appsettings.Development.json`.
|
|
3. **Develop & Verify**:
|
|
- Commit markdown and images to your branch/fork.
|
|
- Run `Fargo3D.Web` locally — it will immediately pull the new structure from your branch without affecting production.
|
|
4. **Merge to Production**:
|
|
- Merge your content branch into `master` on `Fargo3d/3DPrintMeetup`.
|