micronomicon/README.md

Micronomicon

A self-hosted web editor for writing Markdown and publishing .mu pages to a NomadNet node.

Write in Markdown → preview as Micron → publish directly to ~/.nomadnetwork/storage/pages/.

---

Requirements

• Docker + Docker Compose
• Python 3.13+ (for local backend development only)
• Node 20+ (for local frontend development only)
• A running NomadNet container named nomadnet (for the restart button)

---

Quick Start (Docker)

# 1. Build the frontend
cd frontend
npm install
npm run build
cd ..

# 2. Create source directories
mkdir -p ~/.nomadnetwork/storage/pages ~/.micron-editor/sources

# 3. Start the stack
docker compose up --build

App is available at http://localhost:8080.

Tailscale HTTPS

tailscale serve --bg https+insecure://localhost:8080

---

Local Development

Run backend and frontend separately with hot reload.

Backend

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

PAGES_DIR=~/.nomadnetwork/storage/pages \
SOURCES_DIR=~/.micron-editor/sources \
uvicorn main:app --reload --port 8080

Frontend

cd frontend
npm install
npm run dev   # proxies /api → localhost:8080

Open http://localhost:5173.

---

Environment Variables

Variable	Default	Description
PAGES_DIR	/data/pages	NomadNet pages directory
SOURCES_DIR	/data/sources	Markdown source files directory
NOMADNET_CONTAINER	nomadnet	Docker container name to restart

---

API Reference

Method	Path	Description
GET	/api/health	Health check
POST	/api/convert	Convert { markdown } → { micron }
GET	/api/pages	List all pages with metadata
GET	/api/pages/{name}	Read page (markdown source + micron output)
POST	/api/pages/{name}	Save { markdown, publish } — draft or live
DELETE	/api/pages/{name}	Delete source and/or .mu file
GET	/api/graph	Graph nodes + edges from parsed link sources
POST	/api/restart	Restart NomadNet Docker container

---

Directory Layout

micronomicon/
  Dockerfile
  compose.yml
  backend/
    main.py           ← FastAPI app + static file serving
    converter.py      ← md2txt wrapper (POST /api/convert)
    pages.py          ← file management (CRUD /api/pages)
    graph.py          ← link parser (GET /api/graph)
    docker_utils.py   ← container restart (POST /api/restart)
    requirements.txt
  frontend/
    src/
      App.tsx
      routes/         ← DashboardView, EditorView, GraphView
      components/     ← dashboard/, editor/, shared/, ui/ (shadcn)
      stores/         ← editorStore, pagesStore (Zustand)
      hooks/          ← useConversion, useGraph, useUnsavedGuard
      lib/            ← utils (cn)

~/.nomadnetwork/storage/pages/   ← published .mu files (NomadNet serves these)
~/.micron-editor/sources/        ← markdown sources (managed by this app)

---

Page Lifecycle

New Page  →  /editor/new  →  Save Draft  →  .md saved to sources/
                          →  Publish     →  .md saved + .mu written to pages/

• Draft — .md exists, no .mu. Not visible on NomadNet.
• Published — both .md and .mu exist.
• Orphan — .mu exists but no .md source (e.g. pages created outside this tool).

---

Tech Stack

Layer	Technology
Backend	Python 3.13 + FastAPI + uvicorn
Converter	md2txt (micron renderer)
Frontend	React 19 + Vite + TypeScript
UI	shadcn/ui + Tailwind CSS v4
Editor	CodeMirror 6
Graph	React Flow + dagre
State	Zustand
Container	Docker + Compose

---

Known Limitations (Phase 1)

• Micron preview is plain text — full terminal rendering comes in a later phase (micron-parser-js iframe)
• [[ link autocomplete not yet implemented (Phase 2)
• Graph view is read-only; click a node to open it in the editor
• No metrics (Phase 4)