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