coulomb/content-explorer
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Seeded repo

Browse source
This commit is contained in:
tegwick 2026-10-12 18:28:16 +02:00
parent 451fb5924c
commit 762707cefe
34 changed files with 1526 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

78
research/OnCoDeepDive.md Normal file
View file

@ -0,0 +1,78 @@
# OnCo technical and UX deep dive
**Observed:** 2026-10-12. **Review basis:** public live site, GitHub README and selected raw source files accessible through web browsing. **Limitation:** complete Git clone/build/test was not possible in this research environment (GitHub host DNS unavailable to container). Findings about selected source files were inspected, but repository-wide coupling, tests and runtime behavior require checkout verification. Do not treat this document as a completed full-code audit.
## Primary references
- https://onco.cc/ — live information architecture and entry points.
- https://github.com/judegomila/OnCo — README, repo layout, licensing and contributor instructions.
- https://raw.githubusercontent.com/judegomila/OnCo/main/package.json — scripts and toolchain.
- https://raw.githubusercontent.com/judegomila/OnCo/main/src/lib/schema.ts — Zod entity schemas.
- https://raw.githubusercontent.com/judegomila/OnCo/main/src/lib/kinds.ts — kind registry, labels/routes.
- https://raw.githubusercontent.com/judegomila/OnCo/main/src/lib/graph.ts — validated graph and backlinks.
- https://raw.githubusercontent.com/judegomila/OnCo/main/src/components/EntityBrowser.tsx — generic sortable/filterable table with domain visuals.
- https://raw.githubusercontent.com/judegomila/OnCo/main/src/components/EntityDetail.tsx — entity details and tabs.
- https://raw.githubusercontent.com/judegomila/OnCo/main/src/app/%5Bkind%5D/page.tsx — static kind index routes.
- https://raw.githubusercontent.com/judegomila/OnCo/main/src/lib/nav.ts — navigation taxonomy.
- https://onco.cc/api/ — published machine-access contract.
## Structural anatomy (observed)
| Element | Upstream location | Reuse assessment |
|---|---|---|
| Content corpus | `src/data/`, `ALL_INPUTS` | Replace with connector-produced projection; don't bundle licensed oncology data |
| Schemas | `src/lib/schema.ts` and `kinds.ts` | Conceptual guide; reimplement as domain-neutral schemas and registries |
| Graph | `src/lib/graph.ts` | Reuse algorithmic patterns: duplicate/dangling validation, forward and reverse links; replace `forCancer` and hardcoded typed fields |
| Browser | `src/components/EntityBrowser.tsx` | High-value reuse candidate, but imports cancer icons, target schematics, approval chips, molecule views and Kind enum; split core table from renderers |
| Detail | `src/components/EntityDetail.tsx` | Extract generic title, TL;DR, evidence, relations and tab shell; create registry-driven panels |
| Index route | `src/app/[kind]/page.tsx` | Static routing and listing pattern; replace `ROUTE_TO_KIND`, `k===cancer` branches and `kindBrowser` switches |
| Nav | `src/lib/nav.ts` | Generate from manifest, not oncology-specific menu |
| Export | `scripts/build-api.ts`, API/OpenAPI scripts | Static snapshot publication is excellent v0.1 baseline; adapt canonical contract |
| CLI/MCP | `packages/`, `mcp/` | Subsequent adapters onto same read contract |
| Fetchers and validators | `scripts/` | Reuse refresh/validation workflow, not specialized cancer APIs |
## Notable implementation details
`Base` in `schema.ts` requires `id`, `kind`, `name`, `tldr`, `summary`, `asOf` and collects citation links, aliases, tags and many explicit relationship arrays such as `cancers`, `drugs`, `targets`, `trials`. Domain subtypes extend this base. In `graph.ts`, `Graph` validates via Zod, indexes by ID/kind, rejects duplicate and dangling IDs and derives backlinks; `forCancer` deliberately performs special oncology traversal. Those are clear refactoring boundaries.
`EntityBrowser.tsx` describes a shared full-width sortable/filterable table. Its `BrowserRow` already has generic `facets`, `cols`, `route`, `name`, `tldr`, `sortKeys`, but it also includes `molecule`, `cancerIcon`, `target`, `schematic`, `sectionIcon` and other domain renderers. It retains filter/search/sort state in URL parameters for shareable, static-export-compatible views. Preserve this behavior and separate domain visuals through an optional widget registry.
The Next.js `[kind]` page generates static paths from `KINDS`/`KIND_META`, which can naturally be replaced by `manifest.kinds`. Its current branches still special-case cancer, drug, target, institution and other domain pages. `package.json` defines `dev`, `build:api`, `build`, `validate`, `typecheck`, `lint`, and Vitest. Its build pipeline also emits embeddings, relatedness, triples and context snapshots: promising later extensions, not MVP dependencies.
## Experience inventory
| Experience | Prioritize | Proposed abstraction |
|---|---|---|
| Search box / command shortcut | P0 | Cross-entity full-text/alias index |
| Broad grouped navigation and spotlight landing | P0 | Dataspace home sections and featured collections |
| Faceted sortable entity browser | P0 | Kind-driven columns, facets, URL query state |
| Entity page with nontechnical TL;DR | P0 | Layout from entity+kind manifest |
| Related objects/backlinks | P0 | Typed directed edges, inverse display labels |
| Source links + freshness | P0 | Entity/claim evidence panel with visible as-of |
| Glossary/tooltips | P1 | Term kind + text reference annotations |
| Graph explorer | P1 | Bounded neighborhood or selection, graceful large-graph limits |
| Saved/bookmarkable views | P1 | URL state first; local storage later |
| Timeline/comparison/reading paths | P2 | Optional view plugins dependent on data capability |
| Ask/agent tools | P3 | Answer over cited corpus with provenance guardrails |
| Oncology-specific body map, molecule spins, clinical guides | Exclude initially | Possible domain-specific extension widgets, not core |
## Why reuse rather than replatform
Retaining Next.js, React, TypeScript, Zod, Tailwind-compatible styling and existing table/navigation patterns minimizes design drift. Introduce the normalized model **at build/projection time**, emitting a view model that existing components can consume. For the first port, a thin compatibility mapper (`CanonicalEntity` → `BrowserRow`) is safer than rewriting the entire presentation stack.
## Legal/security review
The upstream README explicitly states MIT **code** and CC BY-NC 4.0 **data**, with permission needed for commercial use of the data. Avoid shipping oncology records as tests. Original software copied/adapted from upstream must retain its MIT notice and copyright notice. Assets, illustrations, screenshots, logos and source data require independent rights review. Do not imply endorsement or use the OnCo name as the product's identity. Validate connector licenses, sanitize HTML/Markdown and outbound URL schemes, and quarantine content with ambiguous permission.
## Open verification tasks on actual clone
1. Pin SHA, enumerate package versions, licenses, source/assets boundaries and copied files.
2. Build upstream baseline, run tests, record accessibility/Lighthouse/screenshots in desktop/mobile.
3. Trace import dependency graph of `EntityBrowser`, `EntityDetail`, `graph`, `kind-browser` and `nav`.
4. Measure coupling via references to cancer-specific constants/files; identify safe incremental extraction points.
5. Run parallel before/after screenshot and interaction snapshots against representative OnCo views.
6. Check whether external package licenses and illustrations introduce obligations beyond MIT.
## Research assessment
Feasible, but **not plug-and-play**: generic graph and table abstractions coexist with extensive oncology special cases. Recommended strategy is a selective fork/extraction with repeatable upstream diff, a strict domain projection seam, and domain-independent acceptance fixtures. Avoid promising parity for the full OnCo site in the first release.

20
research/RisksAndAlternatives.md Normal file
View file

@ -0,0 +1,20 @@
# Risks, countermeasures, alternatives
| Risk | Impact | Response |
|---|---|---|
| OnCo evolves quickly | Cherry-pick conflicts | Pin SHA; maintain provenance diff and minimal extraction |
| Partial upstream audit | Surprise dependencies | WP-00 build + import graph + component classification |
| Misread MIT scope | Copyright/legal exposure | Separate code/data/assets; retain original MIT notice |
| Universal graph model too vague | Lost semantics | Domain manifest + typed predicates + preserved source claims |
| Overfitted universal model | Inflexible connector mappings | Core envelope plus extensible typed properties |
| Untraceable ingested claims | False confidence | Claim+Evidence lineage, block unsupported public claims |
| Duplicate identities | Corrupted graph | Source-qualified IDs, explicit equivalence registry |
| URL state drift | Broken shared views | Browser compatibility/e2e tests |
| Large graphs | UI unusable | Bounded neighborhood, paged indexes and lazy loading |
| Untrusted Markdown / remote content | XSS/SSRF | Safe parsers, sanitizer, URL policy, no execution |
| License contagion from imports | Publishing restrictions | Rights gate, attribution manifest, quarantine |
| Premature LLM question-answering | Hallucination | Defer until retrieval and evidence-grade evaluation |
## Alternatives
**A: Fork whole OnCo and replace content.** Fast visual parity but creates cancer-specific technical debt and major removal effort. **B: Fresh rewrite mimicking look.** Cleaner model but forfeits proven table/route work and carries UX drift risk. **C: Selective upstream extraction with canonical adapter (recommended).** Moderate integration cost and sustainable domain independence; requires careful upstream audit. Gate C against measurable coupling. If extraction crosses a predefined complexity threshold (record in WP-00), switch to B for affected components only.

22
research/UXParityMatrix.md Normal file
View file

@ -0,0 +1,22 @@
# OnCo → Content Explorer UX parity matrix
| Pattern | Reference | v0.1 target | Reuse path | Test |
|---|---|---|---|---|
| Editorial landing and global search | onco.cc home | Adapt | Header/home shell; dynamic title/category cards | Switch domain and labels update |
| Kind directory | `/[kind]/` | Adapt | Dynamic kind route from manifest | Both manifests render |
| Faceted table | `EntityBrowser.tsx` | Strong reuse | Extract `BrowserRow` / facets/columns | URL filtering, sorting |
| Deep-linked view state | `EntityBrowser.tsx` | Strong reuse | URL q/facets/sort | Reload retains state |
| Object detail | `EntityDetail.tsx` | Adapt | Generic tabs and property renderers | Same component for 2 domains |
| Backlinks | `graph.ts` | Reimplement core | Canonical typed edges and reverse index | All inbound/outbound visible |
| Source evidence | `schema.ts` / detail | Extend | Claim/source lineage display | Every cited display links to origin |
| Glossary tooltip | `Tip.tsx` | Later | Term-kind annotation | Graceful absence |
| Graph Explorer | public site | P1 | Neighbor-based generic viewer | Bounded graph, focus change |
| Collections/reading paths | public site | P2 | Manifest collection | Guided route |
| Timelines/comparisons | public site | P2 | Optional widget capabilities | Not rendered when unsupported |
| Static API | `build-api` | P1 | `snapshot.json` then versioned endpoint | Contract validation |
| Ask / MCP | upstream packages | P3 | Common read contract | Explicitly deferred |
| Cancer anatomy/clinical actions | public site | Excluded | No generic analogue | No medical specificity leaked |
## Visual acceptance
At WP-00 capture desktop and narrow-screen reference views of homepage, directory, entity page, filtered table, related-items view. Use these screenshots as inspiration/benchmark, not redistribute without review. Compare spacing, hierarchy, readable density, color tokens, accessible contrast, empty states, keyboard paths, tooltip behavior and URL/history semantics. Record intentional deviations (branding, medical tools, sources).