Meta Museum Development Roadmap

Meta Museum is a public-facing Linked Art web app by Sun & Rain Works. It helps visitors, students, researchers, editors, and AI agents explore museum collection data from sources such as Getty and The Met without losing provenance, rights, citations, uncertainty, or source context.

Meta Wiki Art is the connected MediaWiki instance that AI agents use for drafting, editing, citation management, review workflows, and publishing reviewed art history content generated from Linked Art data sources. Meta Museum is the public experience and data workbench; Meta Wiki Art is the governed publishing layer.

Product Thesis

Museums publish rich open collection data, but it is hard for most people to browse, compare, cite, and transform into reliable educational or research content. Meta Museum should make that data legible for humans and structured enough for AI agents to use safely.

The product succeeds when a visitor can understand an artwork, a student can learn from it, a researcher can trace the source data, an editor can prepare a reviewed page, and an AI agent can generate useful drafts without inventing facts.

Product Separation

• Meta Museum is the public website, discovery interface, and data workbench.
• Linked Art JSON-LD and normalized provider records are the source-of-truth data layer.
• PostgreSQL/JSONB should hold application state, imported records, drafts, rights decisions, and audit events.
• A graph store should hold entity relationships, provenance paths, authority links, and pattern-discovery structures.
• Meta Wiki Art is the MediaWiki publishing layer for reviewed narrative pages, citations, edits, discussion, and revision history.
• AI agents may draft and update Meta Wiki Art pages, but public edits must pass rights checks, citation checks, validation, and human approval gates.

Audience Paths

| Audience | Primary Need | Product Path |

| --- | --- | --- |

| Public visitor | Explore artworks visually and understand basic context | Home, Artwork Gallery, Artwork Detail |

| Student | Learn art history concepts through guided context | Student Mode, timelines, glossary, source notes |

| Researcher | Inspect provenance, metadata, source records, and uncertainty | Scholarly Detail, Linked Art Inspector, Graph Explorer |

| Editor | Prepare reviewed pages and citations | Record Workspace, Rights Review, Meta Wiki Art Drafts |

| AI agent | Read normalized data, run validations, draft content, monitor updates | Agent APIs, job queues, validation reports, dry-run publishing |

| Maintainer | Operate ingestion, monitoring, quality, and deployments | Admin/ops views, logs, CI, automated tests |

Information Architecture

Public Site

• Home: search-first entry, source highlights, featured works, project explanation.
• Explore: image-first gallery with source, rights, culture/period/medium, and import state filters.
• Artwork Detail: public summary, image, maker, date, medium, location, rights, source links.
• Stories: curated paths across themes, people, places, periods, and movements.
• Compare: side-by-side artworks, metadata, timelines, and provenance.
• About Data: clear explanation of Linked Art, sources, rights, and attribution.

Research Workspace

• Records: imported normalized records and raw JSON.
• Linked Art Inspector: JSON-LD conformance, endpoint routing, HAL/discovery checks.
• Graph Explorer: people, places, objects, concepts, events, provenance, and source links.
• Pattern Discovery: unknown makers, uncertain dates, shared concepts, source gaps.
• Rights Review: image/text licenses, attribution, allowed reuse, publication warnings.

Agent + Publishing Workspace

• Agents: run, inspect, and audit agent workflows.
• Jobs: ingestion, pattern scan, source refresh, draft generation, page update checks.
• Meta Wiki Art Drafts: wiki markup dry-runs, citations, rights templates, approval state.
• Issue Monitor: Linked Art GitHub issue inventory and standards follow-up.

Current Prototype

The local app runs at `http://localhost:4173` and includes:

• Public Meta Museum home screen.
• Getty + Met artwork explorer with image cards and detail panels.
• Getty REST, IIIF, ActivityStream, and SPARQL integration.
• Met departments, search, object fetch, and Open Access image integration.
• Linked Art-style import for Getty and Met records.
• Rights and attribution checks for agent-safe reuse.
• Phase 1 shared structure contracts for names, identifiers, statements, time spans, dimensions, digital links, entity summaries, and activity summaries.
• SourceRecord validation now checks primary/display names, structured statements, production timespans, and activity-centric object modeling.
• Linked Art JSON-LD inspect/import workflow.
• GitHub issue inventory for `linked-art/linked.art`.
• Pattern scan, agent run, and content-generation stubs.
• Roadmap API at `/api/roadmap`.

Product Principles

• Source data first: generated content must trace back to records, URLs, rights, and citations.
• Scope by use case: every data-modeling or UI addition must serve a real visitor, student, researcher, editor, or agent path.
• Progressive disclosure: public pages stay readable; scholarly and agent/debug layers remain available.
• Human approval for publication: agents can draft, suggest, and maintain, but not silently publish public pages.
• Rights-aware by default: images and text must carry reuse status and attribution.
• Linked Art compatibility: use activity-based CIDOC-CRM/Linked Art patterns for production, provenance, acquisition, exhibition, statements, time spans, and uncertainty.
• JSON-LD first: imported source snapshots, normalized records, validation reports, and exports must preserve Linked Open Data semantics.
• Web-native APIs: public Linked Art-compatible data should be reachable through stable HTTPS GET resources, HAL links, ActivityStreams paging, and HTML `describedby` discovery where applicable.
• Multi-source normalization: Getty, The Met, and future providers map into one internal shape without hiding provider-specific fields.
• Accessibility and pedagogy: the product must work for non-technical visitors, students, keyboard users, and screen readers.

Architecture Decision: Next.js Timing

Recommendation: keep developing forward in the current Node/vanilla prototype until the data contracts, validation pipeline, persistence model, and first-class entity pages are stable. Do not create a parallel `web/` app yet.

Next.js is still the likely production frontend, but it should be an extraction target rather than the next immediate task. Migrating now would spend effort recreating screens while the hard parts are still the Linked Art entity model, graph traversal, rights handling, validation, source snapshots, and provider normalization. The current app is useful as a low-friction lab for those decisions.

Migration triggers:

• The core contracts for Artwork, SourceRecord, RightsReport, Citation, WikiDraft, AgentTask, ImportJob, and first-class graph entities are stable.
• Public routes are proven in the prototype: home, explore, artwork detail, people, places, concepts, activities/provenance, sets, stories, compare, and about data.
• PostgreSQL/JSONB and the first graph projection exist, with migration and seed workflows.
• Auth, role gates, and editor/admin workflows have a real storage layer to protect.
• The Next.js migration can be done route by route against existing API contracts rather than by rewriting data behavior inside React components.

Target Architecture

| Layer | Target | Current | Next Step |

| --- | --- | --- | --- |

| Frontend | Next.js, TypeScript, accessible design system | Static HTML/CSS/JS | Keep the prototype through contract and graph hardening; later migrate route by route. |

| API Gateway | Provider adapters, auth, rate limits, cache | Node HTTP server | Split `server.js` into route modules and contracts before changing frameworks. |

| Provider Adapters | Getty, Met, Linked Art, Wikidata/AAT/ULAN | Getty + Met + Linked Art prototype | Add normalized provider interface and cache policy. |

| Linked Art Entity API | GET endpoints for physical objects, digital objects, people, groups, places, concepts, activities, sets, textual works, and visual works | Artwork-oriented prototype endpoints | Add first-class entity contracts and HAL search/referrer links. |

| Validation | Official Linked Art JSON Schema, PyLD, SHACL, and friendly heuristic checks | Heuristic checks | Add formal validation reports. |

| Persistence | PostgreSQL JSONB + graph store | Local JSON files | Add schema, migrations, seed data, and import jobs. |

| Search | Faceted metadata + semantic/vector search | Client filtering + provider search | Add indexed search over imported records. |

| Graph | Neo4j/Stardog or RDF store | Simple node list | Add event/provenance graph queries. |

| Agents | Tool registry, queues, memory, evals, approvals | Local stubs | Add durable jobs, audit logs, and tool contracts. |

| Meta Wiki Art | MediaWiki API, draft namespace, templates | Planned | Build dry-run wiki markup endpoint first. |

| Observability | Logs, metrics, source sync reports, test dashboards | Minimal local logs | Add health checks and CI reports. |

Design System Direction

• Visual tone: modern, calm, museum-quality, readable, not dashboard-heavy on public pages.
• Palette: white base with black text, controlled orange/yellow/green/blue accents from Sun & Rain Works.
• Layout: public pages should lead with artwork imagery and concise context; research tools can be denser.
• Navigation: separate public discovery from research/admin/agent tools.
• Components: ArtworkCard, ArtworkDetail, SourceBadge, RightsBadge, CitationBlock, LinkedDate, ProvenanceStepper, AgentTaskCard, WikiDraftPreview.
• Accessibility: keyboard navigation, visible focus, text alternatives, semantic headings, responsive layouts, and color contrast checks.

Engineering Standards

• Keep provider-specific logic in adapters and normalize into one internal artwork/record model.
• Treat imported records as immutable source snapshots; store transformations and generated content separately.
• Model maker, owner, location, exhibition, acquisition, and provenance relationships through activities/events rather than direct string shortcuts.
• Preserve `id`, `type`, `_label`, `identified_by`, `classified_as`, `equivalent`, `part_of`, activity, timespan, statement language, IIIF, rights, and source fields during import and export.
• Use opaque URIs in code; do not infer entity type, provider, or semantics from URI string structure when structured fields are available.
• Use `equivalent` for authority reconciliation to Wikidata, Getty AAT/ULAN, and other identifiers; do not collapse records into `owl:sameAs`-style identity.
• Add tests around rights analysis, provider normalization, Linked Art inspection, and wiki draft generation.
• Prefer typed contracts before adding new UI: request/response schema, validation shape, error shape.
• Use defensive network behavior: provider timeouts, retry limits, cache, and graceful fallbacks.
• Never publish generated content without source citations, rights status, and review state.
• Validate public JSON-LD against official Linked Art schemas before treating an endpoint as production-ready.
• Keep graph relationship labels mapped through the local relationship registry so public UI copy and machine-readable predicate keys stay aligned.
• Run `/api/best-practices` before closing each roadmap phase and convert high-priority gaps into roadmap tasks.

Quality Gates

Before a feature is considered done:

• It has a clear user path and empty/error/loading states.
• It preserves source URL, provider, rights, attribution, and import timestamp.
• It preserves Linked Art semantics and does not flatten first-class actors, places, concepts, digital objects, visual works, or activities into untraceable display strings.
• Public JSON-LD responses include stable identifiers, Linked Art context, HAL links where useful, and schema-validation status.
• It has at least one automated test for risky data transformation.
• It is keyboard usable and does not depend on color alone.
• It has a documented API or component contract if agents or other views use it.
• It has a rollback-safe storage or migration plan if it writes data.

Phased Plan

Phase 0: Prototype Hardening and Public UX, Weeks 1-2

Status: completed.

Deliverables:

• Refined public Home and Explore flows.
• Clear information architecture separating public, research, agent, and wiki layers.
• Provider-aware Getty and Met source integrations.
• Rights-aware display policy.
• Roadmap and quality bar documented.

Completion audit:

• Public Home, Explore, and Artwork Detail surfaces exist in the current app.
• IA separates public discovery, research tools, agent/publishing work, and roadmap views.
• Getty and Met integrations are split into adapter modules and covered by adapter tests.
• Rights status, attribution, source URLs, warnings, and import state are preserved in public artwork DTOs.
• The roadmap and quality bar are available in both `docs/development-roadmap.md` and `/api/roadmap`.
• A living best-practices audit is available at `/api/best-practices`.

Phase 1: Data Contracts and Validation, Weeks 3-5

Status: completed.

Deliverables:

• Normalized Artwork, SourceRecord, RightsReport, Citation, AgentTask, WikiDraft, ImportJob, EntitySummary, ActivitySummary, Name, Identifier, TimeSpan, Dimension, Statement, and DigitalLink contracts.
• Formal JSON-LD/Linked Art validation reports using official schemas where possible, plus friendly heuristic warnings.
• Provider adapter modules for Getty and Met.
• Initial tests for normalization, rights analysis, and imports.
• First pass at required/recommended/listed metadata tiers, including primary names and AAT-oriented classifications.

Completed:

• Added reusable Linked Art shared structures in `src/contracts/shared-structures.js`.
• Added SourceRecord validation for primary/display names, structured statements, production timespans, arrays, rights fields, dimensions, equivalents, and activity-centric HumanMadeObject records.
• Added Citation, WikiDraft, AgentTask, and richer ImportJob contracts for agent and publishing workflows.
• Added a provider adapter descriptor and cache policy contract before adding more providers.
• Added a representative hand-authored Linked Art fixture for validation tests.
• Added local Linked Art schema-profile validation reports and required/recommended/listed metadata-tier reports.
• Added contract, adapter-interface, validation-report, normalization, and rights tests; local suite now covers 37 tests.

Notes:

• Full official JSON Schema execution is intentionally deferred until dependency management is introduced. Current validation is dependency-free, points to the official Linked Art schema documentation, and keeps friendly heuristic warnings for users and agents.
• Phase 2 should now build public routes/components on top of these contracts rather than introducing a parallel Next.js app.

Phase 2: Public Artwork Pages and Search, Weeks 6-8

Status: in progress.

Deliverables:

• Public artwork detail routes.
• Faceted browse by source, maker, date, place, material, classification, rights, image availability, and first-class linked entities.
• Source and citation components.
• UI logic for primary names, alternative names, identifiers, physical objects versus digital images/IIIF services, and click-through graph pivots.
• Responsive and accessibility QA pass.

Completed in this slice:

• Public `/artwork/:id` detail resolution now supports imported records and live Getty/Met candidate records.
• Artwork DTOs now carry primary names, alternative names, identifiers, linked entities, digital objects, and citation summaries.
• Explorer API responses now include tested facet buckets for makers, date bands, places, materials, classifications, and sources.
• Explorer UI now exposes facet controls for maker, date, place, material, and type in addition to source, text, rights, import, and image filters.
• Artwork detail pages now distinguish the physical object from digital objects and expose graph-pivot entities for people, places, concepts, materials, owners, and equivalents.
• Public `/entity/:id` routes now expose first-class entity profiles for people, places, concepts, materials, groups, activities, digital objects, sets, and source records found in imported Linked Art records.
• Entity profiles show relationship context, related artworks, names, identifiers, classifications, and equivalence links.
• Entity and artwork graph pivots now carry friendly labels plus stable predicate keys from a relationship registry.
• `/api/best-practices` audits the current records and roadmap against Linked Art design, API, JSON-LD, pipeline, UI, relationship, shared-structure, and QA standards.

Next actions:

• Extract SourceBadge, RightsBadge, CitationBlock, LinkedDate, ArtworkCard, and ProvenanceStepper into reusable frontend component patterns within the vanilla app.
• Add keyboard/focus QA for gallery cards, filters, detail navigation, and provenance/entity lists.
• Expand entity profiles from imported-record graph extraction into provider-backed live lookup where available.
• Address `/api/best-practices` P0/P1 recommendations as recurring quality work.
• Add compare/story routes once the detail and entity surfaces are stable.

Phase 3: Research and Graph Tools, Weeks 9-11

Deliverables:

• Dynamic Graph Explorer with event/provenance paths.
• Pattern Discovery workspace.
• Authority reconciliation with Getty AAT/ULAN and Wikidata.
• Export to JSON-LD, CSV, and citation formats.
• First-class profile pages for people, groups, places, concepts, activities, digital objects, visual works, textual works, and sets.
• Part-to-whole traversal for physical, spatial, linguistic, conceptual, and collection relationships.

Phase 4: Agent Workflows and Meta Wiki Art Drafting, Weeks 12-15

Deliverables:

• Durable agent job queue.
• Wiki draft generation dry-run endpoint.
• Citation and rights templates for Meta Wiki Art.
• Human approval workflow before publishing.
• Audit trail for prompts, sources, transformations, and edits.

Phase 5: Production Architecture and Publishing, Weeks 16-20

Deliverables:

• Route-by-route Next.js migration or equivalent production frontend, only after contracts and persistence are stable.
• PostgreSQL/graph persistence.
• MediaWiki integration with draft namespace and bot credentials.
• CI/CD, tests, monitoring, and source refresh jobs.
• Public beta release checklist.

Immediate Build Queue

| Priority | Work | Agent Instruction |

| --- | --- | --- |

| Done | Define normalized data contracts | Artwork, SourceRecord, RightsReport, Citation, WikiDraft, AgentTask, ImportJob, and shared Linked Art structures are implemented. |

| Done | Add Linked Art shared structures | Reusable Name, Identifier, Statement, TimeSpan, Dimension, DigitalLink, EntitySummary, and ActivitySummary contracts are implemented and tested. |

| Done | Add Phase 1 validation reports | Local schema-profile reports and required/recommended/listed metadata-tier checks are implemented and tested. |

| Done | Define provider adapter interface | Provider descriptor and cache policy contracts are implemented and tested. |

| P0 | Refine public IA and navigation | Separate public discovery from research/admin/agent tools and define page-level routes for Phase 2 screens. |

| Done | Add public artwork detail page | Detail routes now support imported and live candidate records with image, maker, date, source, rights, citation, digital object, and graph-pivot panels. |

| P0 | Define Meta Wiki Art publishing contract | Specify namespaces, citation templates, rights templates, generated-content audit notes, and approval gates. |

| P1 | Add provider adapter modules | Split Getty and Met fetching/normalization into maintainable service modules. |

| P1 | Add tests for normalization and rights | Cover Getty image rights, Getty text rights, Met public-domain handling, and import mapping. |

| Done | Add Linked Art schema validation | Dependency-free schema-profile validation and metadata-tier reporting are wired into inspect/import reports. |

| P1 | Draft design system components | Extract reusable frontend component patterns for ArtworkCard, RightsBadge, SourceBadge, CitationBlock, LinkedDate, and ProvenanceStepper. |

Open Architecture Decisions

• Whether the production API gateway should be Node-first, FastAPI-first, or hybrid.
• Whether graph storage should be RDF-native, Neo4j, or PostgreSQL plus RDF export.
• Which MediaWiki extensions are required for citations, semantic metadata, and agent audit trails.
• Whether generated wiki drafts should be stored as wiki markup, structured JSON, or both.
• How much source-provider raw JSON should be exposed publicly versus reserved for research/debug views.