@hippo-digital/hippocampus 1.0.0-rc.1

package/docs/source-model.md

@@ -0,0 +1,252 @@
+# Source Model
+
+The knowledge base is driven by structured JSON in `hippocampus/source`.
+
+The source model is intentionally small. It should be easy for humans to inspect and easy for agents to update safely.
+
+For the explicit graph layer, research entities and research artefact import/promotion process, read `docs/research-knowledge-graph.md`.
+
+## Validation
+
+Run:
+
+```bash
+npx hippocampus validate
+```
+
+Validation has two layers:
+
+1. Schema validation in `node_modules/@hippo-digital/hippocampus/lib/schema.js`
+2. Relationship validation in `node_modules/@hippo-digital/hippocampus/lib/load-knowledge.js`
+
+Schema validation checks:
+
+- required fields
+- lowercase kebab-case IDs
+- enum values
+- route format
+- nested journey-step structure
+
+Relationship validation checks:
+
+- user needs link to users and evidence
+- scenarios link to users and needs
+- journeys link to scenarios
+- journey steps link to needs, screens, evidence and decisions
+- screens link to user needs
+
+## Records
+
+### Project
+
+File: `hippocampus/source/project.json`
+
+Defines the small project identity used by the viewer:
+
+- project ID
+- name
+- description
+- phase
+- service area
+- prototype slice
+
+### Project context
+
+File: `hippocampus/source/project-context.json`
+
+Defines broader project-level material that is useful across the whole prototype but is not itself research insight:
+
+- purpose
+- vision
+- problem statement
+- service proposition
+- project-level users
+- service channels
+- policies and regulations
+- constraints
+- risks
+- milestones
+- source facts
+- project overview artefacts
+
+Use project context for overview boards, propositions, service maps, policy summaries and other generic briefing material.
+
+Do not force this material into `research-rounds.json` unless it is genuinely a research session or research artefact.
+
+### Users
+
+File: `hippocampus/source/users.json`
+
+Defines user groups. Users are linked from needs and scenarios.
+
+Each user includes:
+
+- responsibilities
+- access needs
+- service context
+
+### User needs
+
+File: `hippocampus/source/needs.json`
+
+Needs are linked to:
+
+- one user
+- one or more evidence items
+- scenarios through `needIds`
+- journey steps through `needIds`
+- screens through `needIds`
+
+Needs should be specific enough to influence journeys and screens.
+
+A need may optionally carry a `reference` (e.g. an external ticket ID such as a Jira key) when it was imported from a source that already tracks it that way.
+
+### Scenarios
+
+File: `hippocampus/source/scenarios.json`
+
+Scenarios describe a user context that can produce a journey.
+
+Each scenario links to:
+
+- one user
+- one or more user needs
+
+Scenarios include:
+
+- trigger
+- context
+- risk level
+- happy path
+- edge cases
+- optional location search detail, when a scenario map contains address, postcode, household or resident-history behaviour
+
+Location search detail captures:
+
+- primary intent
+- search scope: `household`, `postcode-area` or `both`
+- trigger conditions
+- available information
+- role of the address
+- what users learn from residents
+- current and historic resident needs
+- outcomes
+- risks
+
+### Journeys
+
+File: `hippocampus/source/journeys.json`
+
+Journeys are the main source for generated journey pages and blueprints.
+
+Each journey links to:
+
+- one scenario
+- journey steps
+
+Each journey step includes the blueprint lanes:
+
+- user action
+- frontstage
+- backstage
+- support processes
+- data dependencies
+- security and governance
+- pain points
+- exception handling
+- evidence and decisions
+
+A step may optionally include `futureState`: proposed or target-state changes that are not yet true of the current journey (e.g. a planned self-serve flow, or an as-is/to-be process still being redesigned). Keep this separate from the as-is lanes above rather than blending proposed changes into them.
+
+`/hippocampus/journeys/:journeyId/flow` generates a Mermaid flowchart directly from a journey's steps (see `buildJourneyFlowDiagram` in `node_modules/@hippo-digital/hippocampus/lib/load-knowledge.js`) - one node per step in sequence, plus a dashed branch to its own node for each real `exceptionHandling` entry. A step's exception text is skipped rather than drawn as a branch if it's exactly `"No exception path was captured for this step in the source blueprint"` - an honest placeholder from importing the NHS Notify blueprint, not a real exception.
+
+### Screens
+
+File: `hippocampus/source/screens.json`
+
+Screens define prototype routes and link prototype UI back to user needs.
+
+Each screen includes:
+
+- route
+- title
+- purpose
+- linked needs
+- expected NHS components
+
+### Evidence
+
+File: `hippocampus/source/evidence.json`
+
+Evidence supports needs and journey steps.
+
+Each evidence item includes:
+
+- source type
+- summary
+- confidence
+- optional source path
+- optional supporting quotes
+
+Use `sourcePath` when the evidence comes from a copied artefact in the repo.
+
+Do not invent evidence. If a claim is not evidenced, add an assumption instead.
+
+### Decisions
+
+File: `hippocampus/source/decisions.json`
+
+Decisions explain modelling or product choices.
+
+Allowed statuses:
+
+- `proposed`
+- `accepted`
+- `superseded`
+- `rejected`
+
+### Assumptions
+
+File: `hippocampus/source/assumptions.json`
+
+Assumptions capture claims or constraints that need later validation.
+
+Use assumptions when:
+
+- evidence is missing
+- a service rule is plausible but unconfirmed
+- the spike makes a deliberate simplification
+
+## Relationship Map
+
+```text
+users
+  -> needs
+      -> scenarios
+          -> journeys
+              -> journey steps
+                  -> screens
+                  -> evidence
+                  -> decisions
+
+screens
+  -> needs
+
+needs
+  -> evidence
+
+assumptions
+  -> currently standalone review items
+
+project-context
+  -> project-level briefing material outside the graph
+```
+
+## Editing Rules
+
+- Preserve existing IDs unless renaming is explicitly requested.
+- Add new IDs in lowercase kebab-case.
+- Update links whenever adding, splitting or deleting records.
+- Run validation before committing.
+- Keep fictional data fictional.
+- Prefer adding an assumption over pretending there is evidence.

package/index.js

@@ -0,0 +1,47 @@
+const express = require('express')
+const { createContext } = require('./lib/context')
+const { createHippocampusRouter } = require('./lib/create-router')
+const packagePaths = require('./lib/package-paths')
+
+/**
+ * The whole public surface. A host wires the viewer with two lines:
+ *
+ *   const hippocampus = require('@hippo-digital/hippocampus').createHippocampus()
+ *   router.use(hippocampus.router)
+ *
+ * and adds `hippocampus.viewsPath` to the kit's viewsPath array. Everything
+ * else - stylesheet, client JS, layout - the viewer serves itself, so there is
+ * no build step and no stylesheet link for the host to get wrong.
+ */
+function createHippocampus (options = {}) {
+  const ctx = createContext(options)
+  const projects = ctx.projects()
+  const router = express.Router()
+
+  for (const project of projects) {
+    router.use(project.basePath, createHippocampusRouter({
+      basePath: project.basePath,
+      knowledgeStore: project.store
+    }))
+  }
+
+  return {
+    router,
+    viewsPath: packagePaths.viewsDir,
+    context: ctx,
+    projects
+  }
+}
+
+module.exports = {
+  createHippocampus,
+  createContext,
+  createHippocampusRouter,
+  packagePaths,
+  createKnowledgeStore: require('./lib/load-knowledge').createKnowledgeStore,
+  createPaths: require('./lib/paths').createPaths,
+  resolveRoot: require('./lib/resolve-root').resolveRoot,
+  lintKnowledge: require('./lib/lint-knowledge').lintKnowledge,
+  schema: require('./lib/schema'),
+  schemaVersion: require('./lib/schema-version')
+}

package/lib/config.js

@@ -0,0 +1,46 @@
+const fs = require('fs')
+const path = require('path')
+const { CONFIG_FILENAME } = require('./resolve-root')
+
+// hippocampus.config.json is the host's anchor: it marks the project root and
+// says where the data lives. It is optional - the defaults below are what an
+// unconfigured project gets - but its presence is also the "is this
+// initialised?" check, so it is never invented on read.
+
+const DEFAULTS = {
+  configVersion: 1,
+  dataDir: 'hippocampus',
+  artefactsDir: 'artefacts',
+  viewer: { basePath: '/hippocampus' }
+}
+
+function readConfig (root) {
+  const configPath = path.join(root, CONFIG_FILENAME)
+  if (!fs.existsSync(configPath)) {
+    return { ...DEFAULTS, viewer: { ...DEFAULTS.viewer }, exists: false, configPath }
+  }
+
+  let raw
+  try {
+    raw = JSON.parse(fs.readFileSync(configPath, 'utf8'))
+  } catch (error) {
+    throw new Error(`${CONFIG_FILENAME} is not valid JSON: ${configPath}\n${error.message}`)
+  }
+
+  if (raw.configVersion && raw.configVersion > DEFAULTS.configVersion) {
+    throw new Error(
+      `${CONFIG_FILENAME} declares configVersion ${raw.configVersion}, but this ` +
+      `version of Hippocampus understands ${DEFAULTS.configVersion}. Upgrade the package.`
+    )
+  }
+
+  return {
+    ...DEFAULTS,
+    ...raw,
+    viewer: { ...DEFAULTS.viewer, ...(raw.viewer || {}) },
+    exists: true,
+    configPath
+  }
+}
+
+module.exports = { readConfig, CONFIG_DEFAULTS: DEFAULTS }

package/lib/context.js

@@ -0,0 +1,59 @@
+const { resolveRoot } = require('./resolve-root')
+const { readConfig } = require('./config')
+const { createPaths } = require('./paths')
+const { discoverProjects } = require('./discover-projects')
+const packagePaths = require('./package-paths')
+
+// One place that turns "wherever this command was run from" into everything a
+// script or the router needs. Scripts call this once at the top instead of
+// requiring paths directly, which is what lets the same code run from the host
+// root, from anywhere with --root, or from a cron job with HIPPOCAMPUS_ROOT set.
+
+function createContext ({ argv, env, cwd } = {}) {
+  const { root, source, configPath } = resolveRoot({ argv, env, cwd })
+  const config = readConfig(root)
+  const paths = createPaths({
+    root,
+    dataDir: config.dataDir,
+    artefactsDir: config.artefactsDir
+  })
+
+  return {
+    root,
+    rootSource: source,
+    configPath,
+    config,
+    paths,
+    package: packagePaths,
+    projects: () => discoverProjects({ root, config }),
+
+    // Commands that operate on a knowledge base call this instead of projects().
+    // Finding none is not "nothing to do" - it means the root is wrong, or the
+    // project was never initialised, and both deserve to be said out loud with
+    // the root printed. Exiting 0 on an empty result is how a misrooted command
+    // reports success for work it never did.
+    requireProjects: () => {
+      const found = discoverProjects({ root, config })
+      if (found.length) return found
+      throw new Error(
+        `No Hippocampus knowledge base found in ${root}\n` +
+        `Root resolved from: ${source}\n` +
+        `Looked for ${config.dataDir}/source/project.json (and any sibling hippocampus* directory).\n` +
+        'Run this from your project, or pass --root <project> / set HIPPOCAMPUS_ROOT.'
+      )
+    }
+  }
+}
+
+// Scripts are CLIs, not libraries. A misrooted command should print one clear
+// line about where it looked and why, not a stack trace through resolve-root.
+function createContextOrExit (options) {
+  try {
+    return createContext(options)
+  } catch (error) {
+    console.error(error.message)
+    process.exit(1)
+  }
+}
+
+module.exports = { createContext, createContextOrExit }

package/lib/create-router.js

@@ -0,0 +1,187 @@
+const express = require('express')
+const path = require('path')
+const packagePaths = require('./package-paths')
+const { listDocs, readDoc, packageVersion } = require('./docs')
+
+function createHippocampusRouter ({ basePath, knowledgeStore }) {
+  const {
+    getKnowledge,
+    getJourney,
+    getUserKnowledgeGraph,
+    getGraphExplorer,
+    getTraceExplorer,
+    getEvidenceImpact,
+    getResearchViewModel,
+    buildBlueprintViewModel,
+    buildJourneyFlowDiagram,
+    validateKnowledge
+  } = knowledgeStore
+
+  const router = express.Router()
+
+  // The viewer serves its own stylesheet and client JS. Copying them into a
+  // host's build is how a page ends up styled by a version of the library the
+  // host no longer has installed - and it costs the host two file edits it
+  // should not need to make.
+  router.use('/assets', express.static(path.join(packagePaths.assetsDir, 'dist'), { fallthrough: true }))
+  router.use('/assets', express.static(path.join(packagePaths.assetsDir, 'javascript'), { fallthrough: true }))
+
+  router.use((req, res, next) => {
+    res.locals.basePath = basePath
+    res.locals.hippocampusAssets = `${basePath}/assets`
+    // Data-browsing pages benefit from the full viewport width rather than
+    // the NHS.UK content-page measure - nhsuk-width-container-fluid is the
+    // frontend's own utility for this (see node_modules/nhsuk-frontend's
+    // template.njk, which already supports a containerClasses override).
+    res.locals.containerClasses = 'nhsuk-width-container-fluid'
+    // A visual identity distinct from the citizen-facing NHS.UK look, scoped
+    // to this body class so /patient and /policy prototype screens (which
+    // should still look like a real NHS.UK page) are unaffected.
+    res.locals.bodyClasses = 'knowledge-admin-theme'
+    const result = validateKnowledge()
+    res.locals.knowledgeValidation = result
+    next()
+  })
+
+  router.get('/', (req, res) => {
+    const knowledge = getKnowledge()
+    res.render('hippocampus/index', { knowledge })
+  })
+
+  router.get('/users', (req, res) => {
+    const knowledge = getKnowledge()
+    res.render('hippocampus/users', { knowledge })
+  })
+
+  router.get('/project', (req, res) => {
+    const knowledge = getKnowledge()
+    res.render('hippocampus/project', { knowledge })
+  })
+
+  router.get('/users/:userId', (req, res) => {
+    const knowledge = getKnowledge()
+    const userGraph = getUserKnowledgeGraph(req.params.userId)
+    if (!userGraph) return res.status(404).render('hippocampus/not-found')
+    res.render('hippocampus/user', { knowledge, userGraph })
+  })
+
+  router.get('/user-needs', (req, res) => {
+    const knowledge = getKnowledge()
+    res.render('hippocampus/user-needs', { knowledge })
+  })
+
+  router.get('/scenarios', (req, res) => {
+    const knowledge = getKnowledge()
+    res.render('hippocampus/scenarios', { knowledge })
+  })
+
+  router.get('/research', (req, res) => {
+    const knowledge = getKnowledge()
+    const research = getResearchViewModel()
+    res.render('hippocampus/research', { knowledge, research })
+  })
+
+  router.get('/graph', (req, res) => {
+    const knowledge = getKnowledge()
+    const graph = getGraphExplorer()
+    res.render('hippocampus/graph', { knowledge, graph })
+  })
+
+  router.get('/trace', (req, res) => {
+    const knowledge = getKnowledge()
+    const trace = getTraceExplorer(req.query.type, req.query.entity)
+    res.render('hippocampus/trace', { knowledge, trace })
+  })
+
+  router.get('/evidence/:evidenceId/impact', (req, res) => {
+    const knowledge = getKnowledge()
+    const impact = getEvidenceImpact(req.params.evidenceId)
+    if (!impact) return res.status(404).render('hippocampus/not-found')
+    res.render('hippocampus/evidence-impact', { knowledge, impact })
+  })
+
+  router.get('/journeys/:journeyId', (req, res) => {
+    const knowledge = getKnowledge()
+    const journey = getJourney(req.params.journeyId)
+    if (!journey) return res.status(404).render('hippocampus/not-found')
+    res.render('hippocampus/journey', { knowledge, journey })
+  })
+
+  router.get('/journeys/:journeyId/blueprint', (req, res) => {
+    const knowledge = getKnowledge()
+    const blueprint = buildBlueprintViewModel(req.params.journeyId)
+    if (!blueprint) return res.status(404).render('hippocampus/not-found')
+    res.render('hippocampus/blueprint', { knowledge, blueprint })
+  })
+
+  router.get('/journeys/:journeyId/blueprint/classic', (req, res) => {
+    const knowledge = getKnowledge()
+    const blueprint = buildBlueprintViewModel(req.params.journeyId)
+    if (!blueprint) return res.status(404).render('hippocampus/not-found')
+    res.render('hippocampus/blueprint-classic', { knowledge, blueprint })
+  })
+
+  router.get('/journeys/:journeyId/flow', (req, res) => {
+    const knowledge = getKnowledge()
+    const flow = buildJourneyFlowDiagram(req.params.journeyId)
+    if (!flow) return res.status(404).render('hippocampus/not-found')
+    res.render('hippocampus/journey-flow', { knowledge, flow })
+  })
+
+  router.get('/route-review', (req, res) => {
+    const knowledge = getKnowledge()
+    const screen = knowledge.index.screens['screen-route-review-workbench']
+    const journey = getJourney('route-review-workflow')
+
+    if (!screen || !journey) return res.status(404).render('hippocampus/not-found')
+
+    const linkedNeeds = screen.needIds
+      .map((needId) => knowledge.index.needs[needId])
+      .filter(Boolean)
+
+    res.render('hippocampus/route-review', { knowledge, screen, journey, linkedNeeds })
+  })
+
+  // Documentation is served from the package rather than copied into the host,
+  // so what a team reads always matches the version they are running.
+  router.get('/docs', (req, res) => {
+    res.render('hippocampus/docs', { docs: listDocs(), packageVersion: packageVersion() })
+  })
+
+  router.get('/docs/:slug', (req, res) => {
+    const doc = readDoc(req.params.slug)
+    if (!doc) return res.status(404).render('hippocampus/not-found')
+    res.render('hippocampus/doc', { doc, packageVersion: packageVersion() })
+  })
+
+  router.get('/handover', (req, res) => {
+    const knowledge = getKnowledge()
+    // With no journeys at all this is an empty knowledge base, not a bad URL.
+    // 404 here would read as "the viewer is broken" on somebody's first run.
+    if (!knowledge.journeys.length) {
+      return res.render('hippocampus/handover-empty', { knowledge })
+    }
+    renderHandover(req, res, knowledge.project.prototypeSlice)
+  })
+
+  router.get('/journeys/:journeyId/handover', (req, res) => {
+    renderHandover(req, res, req.params.journeyId)
+  })
+
+  function renderHandover (req, res, journeyId) {
+    const knowledge = getKnowledge()
+    const blueprint = buildBlueprintViewModel(journeyId)
+    if (!blueprint) return res.status(404).render('hippocampus/not-found')
+
+    const screens = uniqueById(blueprint.steps.flatMap((step) => step.screens))
+    res.render('hippocampus/handover', { knowledge, blueprint, screens })
+  }
+
+  return router
+}
+
+function uniqueById (items) {
+  return Object.values(Object.fromEntries(items.map((item) => [item.id, item])))
+}
+
+module.exports = { createHippocampusRouter }

package/lib/discover-projects.js

@@ -0,0 +1,45 @@
+const fs = require('fs')
+const path = require('path')
+const { createPaths } = require('./paths')
+const { createKnowledgeStore } = require('./load-knowledge')
+
+/**
+ * Finds every Hippocampus knowledge base in a host project.
+ *
+ * An explicit `knowledgeBases` list in hippocampus.config.json wins when it is
+ * present, so a project can name its bases and their mount points. Otherwise
+ * the directory scan is the fallback: sibling `hippocampus*` directories under
+ * the root that contain a `source/project.json`, which means adding a base
+ * never requires editing the scripts that validate and smoke-test them all.
+ */
+function discoverProjects ({ root, config = {} } = {}) {
+  if (!root) throw new Error('discoverProjects requires a resolved root - see resolve-root.js')
+
+  const artefactsDir = config.artefactsDir || 'artefacts'
+  const declared = Array.isArray(config.knowledgeBases) ? config.knowledgeBases : null
+
+  const entries = declared
+    ? declared.map((base) => ({
+        name: base.name || path.basename(base.dir),
+        dir: path.isAbsolute(base.dir) ? base.dir : path.join(root, base.dir),
+        basePath: base.basePath || `/${base.name || path.basename(base.dir)}`
+      }))
+    : fs.readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && /^hippocampus(-|$)/.test(entry.name))
+        .map((entry) => ({
+          name: entry.name,
+          dir: path.join(root, entry.name),
+          basePath: `/${entry.name}`
+        }))
+
+  return entries
+    .filter((entry) => fs.existsSync(path.join(entry.dir, 'source/project.json')))
+    .map((entry) => ({
+      name: entry.name,
+      basePath: entry.basePath,
+      dir: entry.dir,
+      store: createKnowledgeStore(createPaths({ root, dataDir: entry.dir, artefactsDir }))
+    }))
+}
+
+module.exports = { discoverProjects }