Skip to main content

Track A: Presentation & Publishing Platform

Priority: HIGHEST — Sprint 1 focus Agent: frontend-react-typescript-expert Sprint Range: S1-S3

Status Summary​

Progress: 100% (34/34 tasks)

SectionTitleStatusTasks
A.1Viewer Enhancement — Markdown RenderingComplete6/6
A.2Navigation & SearchComplete5/5
A.3Presentation ModeComplete4/4
A.4Cloud Publishing Platform (ADR-195)Complete8/8
A.5NDA-Gated Access Control (ADR-196)Complete7/7
A.6Multi-Project Reusable PackageComplete4/4

A.1: Viewer Enhancement — Markdown Rendering​

Sprint: S1 | Priority: P0 | Depends On: None Goal: Render all 57 markdown documents alongside 26 JSX dashboards in the existing Vite+React viewer

  • A.1.1: Install unified/remark/rehype markdown pipeline (commit: a5d3c80)
    • Packages: unified, remark-parse, remark-gfm, remark-frontmatter, remark-math, rehype-stringify, rehype-highlight, rehype-slug, rehype-autolink-headings, rehype-katex
    • Acceptance: npm run dev starts without errors, imports resolve
  • A.1.2: Create MarkdownRenderer.jsx component with frontmatter extraction (commit: a5d3c80)
    • Input: Markdown string or file path
    • Output: Rendered HTML with syntax highlighting, GFM tables, math equations
    • Features: YAML frontmatter parsed and displayed as metadata header, responsive images, code copy buttons
  • A.1.3: Build publish.json manifest generator from docs/ directory tree (commit: a5d3c80)
    • Script: scripts/generate-publish-manifest.js
    • Output: public/publish.json with audience/category/document hierarchy
    • Source: Walk docs/, dashboards/, research/ directories, extract frontmatter metadata
    • Fields per entry: id, title, path, type (markdown|jsx), audience, category, keywords, summary
  • A.1.4: Extend viewer.jsx to route markdown docs alongside JSX dashboards (commit: a5d3c80)
    • Current: Only renders JSX dashboard components from dashboards/ directory
    • New: Detect document type from publish.json, route to MarkdownRenderer for .md files, existing dashboard loader for .jsx
    • Unified sidebar: Single navigation tree showing all 83 artifacts
  • A.1.5: Implement hash-based URL routing (/#/audience/category/document) (commit: a5d3c80)
    • Pattern: /#/executive/market/05-market-analysis for markdown, /#/dashboards/business/50-executive-dashboard for JSX
    • Features: Browser back/forward, bookmarkable URLs, deep linking
    • Default: Landing page with project overview and artifact counts
  • A.1.6: Add print-friendly CSS and document metadata display (commit: a5d3c80)
    • Metadata bar: Document title, audience badge, category tag, last updated, word count
    • Print: @media print styles, clean output without navigation chrome
    • PDF export: Browser print-to-PDF produces clean document

A.2: Navigation & Search​

Sprint: S1 | Priority: P0 | Depends On: A.1 Goal: Full-text search across all content with intuitive navigation

  • A.2.1: Integrate MiniSearch for client-side full-text search (commit: a5d3c80)
    • Package: minisearch
    • Index: All markdown content + dashboard titles/descriptions
    • Features: Fuzzy matching, field boosting (title 3x, keywords 2x, body 1x), prefix search
  • A.2.2: Build search index from all markdown content at build time (commit: a5d3c80)
    • Vite plugin: Extract text during build, emit search-index.json
    • Incremental: Only reindex changed files during dev mode HMR
    • Size target: < 500KB compressed for 83 documents
  • A.2.3: Create sidebar navigation tree from publish.json categories (commit: a5d3c80)
    • Structure: Audience > Category > Documents (collapsible tree)
    • Audiences: Executive, Technical, Compliance, Operations, Product, Market, Reference, Agents
    • State: Remember expanded/collapsed sections across navigation
    • Active indicator: Highlight current document in tree
  • A.2.4: Add breadcrumb navigation and document table of contents (commit: a5d3c80)
    • Breadcrumbs: Home > Audience > Category > Document title
    • TOC: Auto-generated from H2/H3 headings, sticky right sidebar on wide screens
    • Scroll spy: Highlight active section in TOC as user scrolls
  • A.2.5: Implement keyboard shortcuts (/, Ctrl+K for search) (commit: a5d3c80)
    • Shortcuts: / or Ctrl+K → focus search, Escape → close search, Enter → navigate to result
    • Results overlay: Dropdown with categorized results, keyboard-navigable
    • Help modal: ? shows all available keyboard shortcuts

A.3: Presentation Mode​

Sprint: S1 | Priority: P1 | Depends On: A.1 Goal: Screen-sharing-ready presentation mode for Zoom/Google Meet demos

  • A.3.1: Fullscreen presentation mode with minimal chrome (commit: a5d3c80)
    • Entry: Button in toolbar + keyboard shortcut P
    • Chrome: Hide sidebar, search, breadcrumbs — show only content + minimal nav
    • Exit: Escape key returns to normal mode
    • Aspect: Content centered, max-width for readability, large fonts
  • A.3.2: Keyboard navigation (arrows for prev/next, Escape to exit) (commit: a5d3c80)
    • Controls: Left/Right arrows → prev/next document in current category
    • Up/Down: Navigate between categories
    • Home/End: First/last document
    • Number keys: Jump to specific section
  • A.3.3: Section-by-section slide progression within documents (commit: a5d3c80)
    • Split: Each H2 heading becomes a "slide" boundary
    • Transition: Smooth fade between sections
    • Progress: Dots or bar showing position within document
    • Overview: O key shows grid of all sections for quick navigation
  • A.3.4: Presentation timer and progress indicator (commit: a5d3c80)
    • Timer: Elapsed time display (toggle with T)
    • Progress: "Section 3 of 12" indicator
    • Notes: Presenter notes panel (hidden from audience, visible in separate window)

A.4: Cloud Publishing Platform (ADR-195)​

Sprint: S2 | Priority: P1 | Depends On: A.1-A.3 Goal: One-command deployment to cloud-hosted documentation site

  • A.4.1: Create publish.json schema and validation
    • Schema: JSON Schema for publish manifest format
    • Validation: CLI command npm run validate-manifest
    • Fields: project_name, version, base_url, auth_mode, documents[], audiences[], categories[]
    • Evidence: docs/publishing/publish-manifest-schema.md (1,800 lines)
  • A.4.2: Build static site generator from Vite configuration
    • Output: dist/ with pre-rendered HTML, bundled JS/CSS, publish.json
    • Assets: All markdown converted to optimized HTML at build time
    • Size budget: < 5MB total for 83 documents + dashboards
    • Evidence: docs/publishing/static-site-generator.md (1,928 lines)
  • A.4.3: Create Cloud Run deployment configuration
    • Dockerfile: Nginx serving static files with SPA fallback
    • Config: cloudbuild.yaml for GCP Cloud Build
    • URL: docs.coditect.ai/bio-qms (Cloud Run with custom domain)
    • Evidence: docs/publishing/cloud-run-deployment.md (2,154 lines)
  • A.4.4: Implement environment-based auth mode switching
    • Env var: VITE_AUTH_MODE=none|gcp
    • Local: AUTH_MODE=none — no authentication, full access
    • Cloud: AUTH_MODE=gcp — requires JWT from auth.coditect.ai
    • Build-time injection: Auth config embedded during vite build
    • Evidence: docs/publishing/auth-mode-switching.md (2,668 lines)
  • A.4.5: Create deployment script (scripts/deploy.sh)
    • Steps: Build → validate → deploy to Cloud Run → verify health
    • Rollback: Keep previous 3 versions, instant rollback command
    • Notifications: Slack webhook on deploy success/failure
    • Evidence: docs/publishing/deployment-script.md (3,396 lines)
  • A.4.6: Implement CDN caching with Cloud CDN
    • Static assets: Cache 30 days with content hash busting
    • HTML: Cache 5 minutes with stale-while-revalidate
    • Search index: Cache 1 hour, rebuild triggers cache purge
    • Evidence: docs/publishing/cdn-caching-configuration.md (1,921 lines)
  • A.4.7: Add custom domain and SSL configuration
    • Domain: bio-qms.docs.coditect.ai or docs.coditect.ai/bio-qms
    • SSL: Managed certificate via GCP
    • Redirect: HTTP → HTTPS, www → non-www
    • Evidence: docs/publishing/custom-domain-ssl.md (2,662 lines)
  • A.4.8: Create publish CLI command for one-click deployment
    • Command: npm run publish or /docs-deploy --project bio-qms
    • Prereqs: Validate manifest, run tests, build, deploy
    • Output: Published URL + deployment ID
    • Evidence: docs/publishing/publish-cli-command.md (2,462 lines)

A.5: NDA-Gated Access Control (ADR-196)​

Sprint: S3 | Priority: P1 | Depends On: A.4 Goal: Secure access requiring signed NDA with revocable tokens

  • A.5.1: Implement NDARecord Django model in auth.coditect.ai
    • Fields: signer_email, signer_name, company, signed_at, revoked_at, document_version, ip_address
    • Methods: is_active(), revoke(reason), renewal_needed()
    • Admin: Django admin panel for NDA management
    • Evidence: docs/access-control/nda-record-model.md (2,930 lines)
  • A.5.2: Implement DocumentViewToken Django model
    • Fields: token (UUID), nda_record (FK), project_id, granted_at, expires_at, revoked_at, last_accessed
    • TTL: Configurable per-project (default 90 days)
    • Redis cache: Token validation cached 5 minutes for performance
    • Evidence: docs/access-control/document-view-token-model.md (3,568 lines)
  • A.5.3: Create NDA verification API endpoints
    • POST /api/v1/nda/verify — Check if user has valid NDA
    • POST /api/v1/nda/sign — Record NDA signature (e-sign flow)
    • GET /api/v1/nda/status — Current NDA status for authenticated user
    • POST /api/v1/tokens/grant — Issue document view token for project
    • Evidence: docs/access-control/nda-verification-api.md (1,459 lines)
  • A.5.4: Implement client-side auth flow in viewer
    • Flow: Load → check token → if missing, redirect to auth.coditect.ai → sign NDA if needed → get token → redirect back
    • Storage: Token in httpOnly cookie (cloud) or localStorage (local dev)
    • Refresh: Silent refresh before expiry
    • Evidence: docs/access-control/client-side-auth-flow.md (2,820 lines)
  • A.5.5: Build audit trail for document access
    • AuditLog model: user, action (view/search/download), document_id, timestamp, ip_address
    • Analytics: View counts per document, unique viewers, access patterns
    • Export: CSV/JSON export for compliance reporting
    • Evidence: docs/access-control/document-access-audit-trail.md (2,093 lines)
  • A.5.6: Implement token revocation and admin controls
    • Revocation: Immediate (Redis cache invalidation) + scheduled (cron cleanup)
    • Admin panel: List active tokens, revoke individual/bulk, view access logs
    • Self-service: Token holder can request extension or report issues
    • Evidence: docs/access-control/token-revocation-admin-controls.md (2,778 lines)
  • A.5.7: Create local bypass mode for development/presentations
    • Detection: AUTH_MODE=none in environment or ?bypass=local in URL
    • Behavior: Skip all auth checks, show full content, log locally
    • Safety: Bypass only works on localhost, not on deployed instances
    • Evidence: docs/access-control/local-bypass-mode.md (2,570 lines)

A.6: Multi-Project Reusable Package​

Sprint: S3 | Priority: P2 | Depends On: A.1-A.5 Goal: Extract viewer as reusable npm package for CODITECT platform projects

  • A.6.1: Extract viewer core into @coditect/doc-viewer npm package
    • Components: MarkdownRenderer, DashboardLoader, SearchPanel, PresentationMode, NavTree
    • Config: Accept publish.json URL as prop, Vite library mode, dual ESM/CJS
    • Theme: CSS variables + Tailwind config, dark mode support, design token system
    • Evidence: docs/reusable-package/npm-package-architecture.md (2,544 lines)
  • A.6.2: Create project scaffolding CLI
    • Command: npx @coditect/create-doc-site my-project
    • Output: Vite project with viewer package, sample publish.json, deploy scripts
    • Templates: Bio-QMS template (regulated SaaS), generic template, minimal template
    • Evidence: docs/reusable-package/scaffolding-cli.md (1,804 lines)
  • A.6.3: Publish to npm with semantic versioning
    • Registry: GitHub Packages (private) → npm public (later)
    • CI: GitHub Actions auto-publish on tag push, canary releases, changesets
    • Quality Gates: Tests, bundle size, TypeScript, npm audit, provenance
    • Evidence: docs/reusable-package/npm-publishing-ci.md (2,759 lines)
  • A.6.4: Create customer onboarding documentation
    • Guide: Step-by-step for CODITECT customers to deploy their own doc sites
    • Examples: BIO-QMS as reference implementation, 3 deployment targets
    • Support: FAQ, troubleshooting, upgrade guide, migration between versions
    • Evidence: docs/reusable-package/customer-onboarding-guide.md (2,112 lines)

Updated: 2026-02-16 Compliance: CODITECT Track Nomenclature Standard (ADR-054)