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

CSS / HTML — Pico CSS

Pico CSS is the styling framework. Strictly stay within it.

• Do not add other CSS frameworks, utility libraries, or icon fonts.
• Prefer pico's class-less semantic HTML: <button>, <section>, <hgroup>, <header>, <nav><ul></ul></nav>, <details>, etc. — let the element itself carry the styling.
• Use <section> for thematic blocks. Do not use <article> (project convention — always reach for <section> instead).
• Buttons: native <button> or <a role="button">. For variants use pico's modifiers (.secondary, .contrast, .outline) — do not invent new button classes. For button groups use role="group".
• Layout: wrap top-level blocks in .container for the centered viewport. Use pico's .grid when a simple responsive grid is needed.
• Forms: rely on pico's default <input>/<textarea>/<select> styling; use aria-invalid for validation states.
• Custom CSS belongs in style.css and must only cover what pico does not provide. Reference pico's CSS custom properties (var(--pico-border-color), var(--pico-muted-color), var(--pico-spacing), var(--pico-card-background-color), etc.) — never hardcode colors or spacing.
• Prefer generic descriptive class names (muted, danger, listing, diary-section) over element-specific ones. Re-use existing classes before creating new ones.
• pico.min.css is the served stylesheet; keep pico.css around only as the unminified reference.

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

Date Formatting

• General UI dates (file listings, metadata): ISO YYYY-MM-DD
• Diary long-form dates: German locale, e.g. Mittwoch, 1. April 2026 — use formatGermanDate in diary.go; Go's time.Format is English-only so locale names are kept in maps keyed by time.Weekday / time.Month

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