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:

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.
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.
True Folder Hierarchy & Categories:
- Files are organized into natural repository directories (challenges/, announcements/, HueForge/, tools/) rather than flat wiki slug naming.
Structured Asset Ingestion:
- Directly loads HueForge/3d-Fuel.json to provide real-time filament hex color palettes, transmissivity values, and filament profiles on /tools.
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:

{
  "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):

{
  "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:

---
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

Create Branch or Fork:
- In meetup.fargo3d.com, create a branch (e.g. v5-content) or fork 3DPrintMeetup to your user account.
Update Local Config:
- Set "Branch": "v5-content" in appsettings.Development.json.
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.
Merge to Production:
- Merge your content branch into master on Fargo3d/3DPrintMeetup.

8.3 KiB Raw Permalink Blame History