cairnquire/docs/milestones/milestone-01-foundation.md

Milestone 1: Foundation

Duration: 2 weeks
Goal: Working server that can serve markdown files as HTML

Tasks

Week 1: Project Setup & Infrastructure

• Initialize monorepo structure

  • apps/server/ with Go module
  • apps/web/ with Vite + Preact + TypeScript
  • packages/protocol/ with protobuf schema
  • docs/ with existing documentation

• Go server skeleton

  • main.go with graceful shutdown
  • Chi router with middleware chain
  • Configuration management (environment variables + config file)
  • Structured logging (slog)

• Database layer

  • libsql connection setup
  • Migration system (golang-migrate)
  • Initial schema (users, documents, document_versions)
  • Query builder / repository pattern

• Docker setup

  • Multi-stage Dockerfile for Go app
  • docker-compose.yml with volume mounts
  • Health check endpoint
  • Non-root user in container

Week 2: Markdown Rendering & Static Serving

• Markdown parser integration

  • Goldmark with all extensions
  • Wiki-link parser: [[Page Name]] → internal link
  • Tag extractor: #tagname → tag link
  • Admonition support: > [!NOTE] blocks
  • Mermaid diagram containers
  • Math markup containers (KaTeX)

• Template system

  • Base layout template (header, nav, footer)
  • Document template with rendered markdown
  • Error page templates (404, 500)
  • Design system CSS custom properties

• Static file serving

  • Content-addressed filesystem setup
  • File upload endpoint (basic)
  • Security headers middleware
  • MIME type detection

• Initial frontend

  • Preact app setup with Vite
  • Basic routing (preact-iso)
  • Hydration entry point
  • CSS design system foundation

Acceptance Criteria

Functional

• Server starts and listens on configurable port (default 8080)
• Database auto-migrates on startup with no manual intervention
• Markdown files render correctly with all extensions:
  • Wiki-links resolve to internal document paths
  • Tags are extracted and displayed
  • Admonitions render with appropriate styling
  • Mermaid diagrams have syntax-highlighted containers
  • Math markup has proper delimiters for KaTeX
• Attachments served with correct Content-Type headers
• 404 and 500 pages render correctly

Non-Functional

• Docker compose brings up full stack with docker-compose up -d
• Container health check passes within 30 seconds
• All Go dependencies pinned in go.sum
• Build is reproducible (same commit → same binary hash)
• No plaintext secrets in code or logs
• Security headers present on all responses:
  • Content-Security-Policy
  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • Referrer-Policy: strict-origin-when-cross-origin

Performance

• Initial page load (TTFB) <100ms for cached documents
• Markdown rendering <50ms for documents <100KB
• Static file serving supports 1000 concurrent requests

Deliverables

1. Working development environment (README with setup instructions)
2. CI pipeline (GitHub Actions or similar) with:
   • Go tests
   • TypeScript type checking
   • Dockerfile build
   • Security scan (govulncheck)
3. API documentation (OpenAPI spec)
4. Database migration files

Risk Mitigation

Risk	Mitigation
Goldmark extension conflicts	Test each extension in isolation, then combined
Docker volume permissions	Document UID/GID requirements, provide setup script
libsql compatibility	Test on both native SQLite and Turso cloud

Definition of Done

• All acceptance criteria pass
• Code review completed
• Documentation updated
• CI pipeline green
• Security scan shows no critical/high vulnerabilities