finalize M06-M12 with Go/SQLite/Synology NAS implementation decisions

2026-01-18 20:29:13 +01:00
parent b86ee54934
commit a76724a3d5
7 changed files with 1009 additions and 377 deletions
--- a/DEV_PORTAL_M12_DOCS.md
+++ b/DEV_PORTAL_M12_DOCS.md
@@ -1,8 +1,59 @@
 # Milestone 12: Documentation Site

-**Status**: Planning
+**Status**: Decided
 **Goal**: Comprehensive documentation for Mosis app developers.

+## Decision
+
+**Hugo + Docsy theme** for self-hosted static documentation:
+
+```
+Framework:    Hugo (Go-based static site generator)
+Theme:        Docsy (technical documentation theme)
+Search:       Pagefind (local, no external service)
+Hosting:      Synology NAS (nginx or Go static server)
+```
+
+### Rationale
+
+1. **Go ecosystem** - Hugo is written in Go, consistent with Portal
+2. **Fast builds** - Hugo compiles thousands of pages in seconds
+3. **No runtime** - Generates static HTML, served directly from NAS
+4. **Docsy theme** - Full-featured docs theme with versioning, search, i18n
+5. **Self-contained** - Pagefind search works offline, no Algolia needed
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Synology NAS                                 │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │  mosis-portal container                                     │ │
+│  │  ├── Go binary (API + Portal UI)                           │ │
+│  │  ├── /static/docs/ → Hugo build output                      │ │
+│  │  └── http.FileServer serves docs at /docs/*                 │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│                                                                  │
+│  /volume1/mosis/                                                 │
+│  └── docs/                                                       │
+│      ├── content/          (Markdown source)                     │
+│      ├── static/           (Images, assets)                      │
+│      └── public/           (Hugo build output → served)          │
+└─────────────────────────────────────────────────────────────────┘
+
+Build pipeline:
+  docs/ (Markdown) ──► hugo build ──► public/ ──► Deploy to NAS
+```
+
+### URL Structure
+
+```
+https://portal.mosis.dev/docs/              # Docs home
+https://portal.mosis.dev/docs/quickstart/   # Getting started
+https://portal.mosis.dev/docs/api/          # API reference
+https://portal.mosis.dev/docs/cli/          # CLI reference
+```
+
 ---

 ## Overview
@@ -557,18 +608,18 @@ function submitFeedback(page, helpful, comment) {

 ## Deliverables

- [ ] Framework selection
- [ ] Information architecture
- [ ] Getting Started content
- [ ] UI design guides
+- [x] Framework selected (Hugo + Docsy)
+- [x] Hosting decided (self-hosted on Synology NAS)
+- [ ] Hugo project setup with Docsy theme
+- [ ] Information architecture (directory structure)
+- [ ] Getting Started content (Quick Start, First App)
+- [ ] UI design guides (RML, RCSS)
 - [ ] Lua scripting guides
 - [ ] API reference (all namespaces)
- [ ] CLI reference
- [ ] Best practices
- [ ] Search integration
- [ ] Version selector
- [ ] Deploy pipeline
- [ ] Feedback system
+- [ ] CLI reference (all commands)
+- [ ] Best practices (performance, security)
+- [ ] Pagefind search integration
+- [ ] Deploy script (hugo build + copy to NAS)

 ---

@@ -602,10 +653,10 @@ function submitFeedback(page, helpful, comment) {

 ## Open Questions

-1. Host docs separately or under main domain?
-2. Community wiki/contributions?
-3. Video tutorial platform (YouTube, embedded)?
-4. Glossary/terminology page?
+1. ~~Host docs separately or under main domain?~~ → Under main domain at /docs/
+2. ~~Community wiki/contributions?~~ → Defer to post-MVP (GitHub PRs for docs)
+3. Video tutorial platform (YouTube, embedded)? → Consider for v1.1
+4. ~~Glossary/terminology page?~~ → Yes, include in Phase 2

 ---