go-doc/prompts/001-master-spec.md

Go-Doc Platform Master Specification

This document serves as the unbroken context audit trail for the complete, production-ready Go + React Markdown documentation and user feedback platform, optimized for the Omarchy OS ecosystem.

1. WORKSPACE, ENVIRONMENT, & DIRECTORY ENCAPSULATION

• Base Workspace: All work must occur exclusively within /home/dnoulet/go/go-doc.
• Backend Directory Isolation: Go source code, routers, storage logic, and handlers must reside in backend/. Initialize the Go module there (go mod init go-doc inside backend/).
• Frontend Directory Isolation: The React application must be scaffolded in frontend/ using Vite, Tailwind CSS, and lucide-react.

2. FLAT-FILE STORAGE & SLUGIFICATION ENGINE (backend/storage/engine.go)

• Data Storage: data/docs/ for raw .md files and data/comments/ for user feedback JSON files (app-name-comments.json).
• Slug Engine: A Go utility must translate arbitrary application titles into lower-case, hyphen-separated strings (e.g., "Core Service API" -> "core-service-api").
• File Handlers: Implement production-ready SaveDoc(slug, content), ReadDoc(slug), and DeleteDoc(slug) using the flat-file system.

3. REST API ROUTING LAYER (backend/main.go / backend/router/router.go)

• HTTP Framework: Set up a clean HTTP router (net/http, Chi, or Gin) inside the backend scope with full CORS middleware enabled for the frontend Vite server.
• API Endpoints:
  • GET /api/docs/:slug -> Returns the raw markdown string.
  • POST /api/docs/:slug -> Creates or completely updates the target markdown file.
  • DELETE /api/docs/:slug -> Permanently removes the target documentation file.
  • GET /api/docs/:slug/comments -> Retrieves the JSON list of user/operator/developer comments.
  • POST /api/docs/:slug/comments -> Appends a new comment struct (ID, Author, Role, Content, Timestamp).

4. DUAL-MODE WYSIWYG & AUDIENCE-SEGMENTED UI (frontend/src/)

• Dynamic Slugs: Routing must allow dynamic paths like /docs/:slug querying the backend API.
• Audience Viewer (DocViewer.jsx): A tabbed navigation reader layout separating specific viewpoints for Users, Operators, and Developers.
• Hybrid WYSIWYG Editor (DocEditor.jsx): A rich editing suite with "Visual Edit (WYSIWYG)" and "Source Code (Markdown)" toggle. Visual mode must track structural edits (Bold, Italic, Code, Headers) and translate them seamlessly into clean Markdown; Source Code mode must provide live split preview.

5. MANDATORY MANDATED AUTOMATION & INFRASTRUCTURE LAYER

• docker-compose.yml: Setup local development containers with host-to-container volume mappings for live synchronization.
• Makefile (CRITICAL / MANDATORY): Must provide error-free targets for the system lifecycle:
  • make infra-up: Spin up containers detached.
  • make infra-down: Tear down infrastructure safely.
  • make backend-run: Execute go run main.go natively from backend/.
  • make frontend-run: Launch the Vite development server.
  • make dev: Concurrently execute backend, frontend, and infrastructure.
  • make test: Run all unit, integration, and BDD tests.
  • make build: Build production React static assets, configure Go backend to serve them natively on / (preserving /api/*), and compile a portable binary.

6. ROBUST VERIFICATION MATRIX: INTEGRATION & BDD TESTING

• Integration Tests (backend/tests/integration_test.go): E2E API tests verifying actual HTTP requests read/write to the local filesystem without mocks.
• BDD Tests (backend/tests/bdd/): Implementation using structured Go BDD syntax/framework.
  • Feature 1: "Given a new application title, When it is saved, Then it should be slugified and written to a Markdown file."
  • Feature 2: "Given an existing documentation page, When a developer adds a comment with a developer badge, Then it should be appended to the JSON array and rendered with a red visual badge."

7. INITIAL DOCUMENTATION SEED & HIGH-VOLUME PERFORMANCE DATA

• Default Document: Seed data/docs/go-doc.md detailing separate layout workflows for Users, Operators, and Developers.
• Performance Seeding Script (backend/scripts/seed_perf_data.go): Routine to populate the flat-file backend with 100+ multi-size markdown files and flood the engine with thousands of mock comments for stress testing.

Execution Directive: Execute this vibe code deployment end-to-end, delivering robust, production-quality code blocks for both Go and React, ensuring the Makefile is fully wired up.