78 lines
7.5 KiB
Markdown
78 lines
7.5 KiB
Markdown
# 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.
|