datascape/CLAUDE.md

CLAUDE.md

Project Overview

datascape is a minimal personal wiki where the folder structure is the wiki. No database, no CMS, no abstraction layer — every folder is a page, and index.md in a folder is that page's content.

Build & Deploy

# Local build (host architecture)
go build .

# Deploy to NAS
make deploy

HTTP API Surface

Method	Path	Behaviour
GET	/{path}/	If folder exists: render index.md + list contents. If not: show empty create prompt.
GET	/{path}/?edit	Mobile-friendly editor with index.md content in a textarea
POST	/{path}	Write index.md to disk; creates the folder if it does not exist yet

Non-existent paths without a trailing slash redirect to the slash form (GET only — POSTs are not redirected because path.Clean strips the trailing slash from PostURL and the content would be lost).

Do not add new endpoints without a concrete stated need.

Code Structure

When adding a new special folder type, create a new .go file. Do not add type-specific logic to main.go or render.go.

Prefer separate, human-readable .html files over inlined HTML strings in Go. Embed them via embed.FS if needed.

Architecture Rules

• Single binary — no installer, no runtime dependencies, no Docker
• Go stdlib net/http only — no web framework
• goldmark for Markdown rendering — no other Markdown libraries
• embed.FS for all assets — no external serving, no CDN
• No database of any kind
• No indexing or caching unless explicitly requested and justified
• Keep dependencies to an absolute minimum; if stdlib can do it, use stdlib

Frontend Rules

• Vanilla JS only — no frameworks, no build pipeline
• Each feature gets its own JS file; global behaviour goes in global-shortcuts.js
• Do not inline JS in templates or merge unrelated features into one file
• ALT+SHIFT is the modifier for all keyboard shortcuts — do not introduce others
• Editor toolbar buttons use data-action + data-key; adding data-key auto-registers the shortcut

Development Priorities

When building features, apply this order:

1. Correctness on the filesystem — never corrupt or lose files
2. Mobile usability (primary editing device is Android over Wireguard VPN)
3. Simplicity of implementation, adhere to KISS
4. Performance

What to Avoid

• Any parallel folder structure (e.g. a separate media/ tree mirroring pages/)
• Over-engineering auth — Basic auth is sufficient for a personal VPN tool
• Heavy payloads or expensive rendering (target CPU: ARMv7 32-bit NAS)
• Suggesting Docker (plain binary is preferred)

Out of Scope (do not implement unless explicitly asked)

• Full-text search
• Browser-based file upload
• Version history / git integration
• Multi-user support
• Tagging or metadata beyond index.md content