119 lines
3.8 KiB
Markdown
119 lines
3.8 KiB
Markdown
# 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
|
|
- embedded templates and static assets under `apps/server/internal/httpserver/`
|
|
- `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 browser UI
|
|
- Go template routes
|
|
- Embedded framework-free browser scripts
|
|
- Progressive enhancement entry points
|
|
- 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
|