# 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`.