initial commit

prompts/001-master-spec.md

@@ -0,0 +1,50 @@
+# 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.