Publicus Product Redesign Prototype

Product Intent

For AI builders

Move fast, but catch vulnerable, unpinned, unknown, or unsupported dependencies before release.

For reviewers

Inspect source-backed evidence, not opaque recommendations. Every claim must have a path.

For trusted contributors

Improve the open substrate through governed source contracts, review proposals, and signed truth.

User Flows

The product should feel like a release cockpit, not a documentation archive. Every path starts from a real user job and ends in an inspectable next action.

Primary builder flow

Entry Upload dependency file

Home and scan use the same upload state model.

Parse Show supported ecosystem count

Unsupported, partial, and unpinned are visible immediately.

Audit Registry plus live evidence

Sources are separated by evidence lane and checked time.

Triage Fix blockers first

Blocked, needs review, unknown, and pass are distinct buckets.

Inspect Open package evidence

Each result links to primary sources and explains the verdict.

Prove Export evidence pack

JSON and Markdown remain reviewable outside the app.

Secondary flows

Audience	Path	Success state
Security reviewer	Open scan result, filter review gaps, inspect source lanes, export proof.	Reviewer can defend the release posture without trusting synthesis.
Package evaluator	Check one AI-suggested package, compare latest metadata, inspect advisories.	Package is accepted, rejected, or queued for review before it enters code.
Registry browser	Browse signed decisions, open component detail, scan that package in context.	Curated baseline is clear without implying internet-wide coverage.
Recent-change reader	Open movement, click affected package or source, inspect changed evidence.	Movement is actionable, not a dead card with hover styling.
Trusted contributor	Find source backlog, read blocker, propose adapter or evidence dispute.	Contribution path improves the public substrate without bypassing review.

Information Architecture

Route	Job	Primary action	Risk to avoid
`/`	Explain the promise and start the scan.	Upload dependency file.	Turning the homepage into a source catalog.
`/scan`	Run the full stack or package audit.	Fix blockers and export proof.	Making unknown feel like unchecked.
`/registry`	Inspect curated signed decisions.	Open component evidence.	Implying the registry is every package on the internet.
`/docs/recent-changes/`	Show movement since the last check.	Open primary source or affected package.	Hover affordance without navigation.
`/ask`	Explain inspected evidence.	Ask a scoped question.	Letting synthesis outrank evidence.

Wireframes And Prototype Screens

These are implementation wireframes, not decorative images. They show layout hierarchy, interaction priority, and evidence flow.

Home: one obvious start

Hero: Build fast with AI. Verify in public.

Upload dropzone

Currentness + proof counts

Why Publicus remains useful beyond model capability

Scan: fix-first audit

Verdict strip: blockers · needs review · unknown · fresh evidence

Fix-first package list

Selected evidence detail

Export proof pack

Package detail: why this verdict?

Registry verdict separate from live evidence

Source lanes: OSV · GHSA · NVD · EPSS · distro · metadata

Primary-source cards with checked time and next action

Sources: active vs backlog

Used in scans · Global context · Needs adapter · License blocked

Source list

Selected contract + blocker

Open primary source

Mobile: single-column audit

Upload and package lookup collapse into one start card

Sticky verdict summary after result

Package detail opens below selected row, not off-canvas

Ask: after evidence only

Selected evidence context

Question box with scoped prompt starters

Answer must cite package, source lane, and checked time

Clickable Prototype States

This lightweight prototype is intentionally built in plain HTML. It gives reviewers and agents a shared model for the live rewrite before production code changes.

Start

Upload the files your AI workflow produced.

Drop package.json, requirements.txt, TOML, Go, Cargo, or SBOM
Click-to-upload and keyboard upload are equal paths.

Before scan

Supported file types are visible before upload.
No file contents are stored or sent to product events.
Primary CTA is scan; docs and Ask are secondary.

Result summary

Review before release

1 blocker

4 need review

7 unknown

14 fresh evidence

Fix first

Blocked and needs-review packages appear before complete package inventory.

Classify unknown

Unknown is labelled outside registry, unpinned, unsupported, partial, unavailable, adapter needed, or license blocked.

Selected package: pyyaml

Needs review because fresh upstream advisories exist and the manifest entry is not exact-version pinned.

Evidence lanes

Registry baseline: not in curated registry.
OSV: advisory matches with primary URL.
EPSS/NVD/GHSA: separate lane status and checked time.
Distro evidence: hidden unless runtime context exists.

Used in scans

Global context

Needs adapter

License blocked

Each source card has two explicit actions

Inspect source contract opens the Publicus schema. Open primary source leaves the app. No card should look clickable without one of these actions.

Evidence selected

Ask receives selected package, source lanes, verdict counts, and checked timestamps.

Scoped answer

The answer explains inspected evidence only. It cannot certify, override, or hide the fix-first verdict.

Interaction Design Rules

Every clickable card must navigate or expand.Hover-only affordance without action is a trust bug.

Drag/drop must have a keyboard path.Click-to-upload remains the canonical accessible path; drag is a convenience.

Unknown is a classified state.outside registry, unpinned, unsupported, partial, unavailable, adapter needed, or license blocked.

Synthesis is never the first verdict.Ask appears after evidence and must cite what it used.

MOMS Test: Product And UX Critique

The redesign must survive a skeptical non-builder test: can a smart reviewer understand what to do, what happened, what is risky, and what proof exists without reading docs first?

Homepage

Failure to avoid: too many equal CTAs and too much source-catalog text.

Pass condition: upload is visually dominant, and secondary paths explain why they exist.

Scan results

Failure to avoid: results read like raw scanner output or hide unknown reasons.

Pass condition: fix-first grouping, classified unknowns, and package-level evidence drilldowns.

Registry

Failure to avoid: curated registry looks like full internet coverage.

Pass condition: curated baseline language and explicit scan path for arbitrary packages.

Recent changes

Failure to avoid: cards look clickable but do nothing.

Pass condition: every movement card opens source, affected package, or an explanation panel.

Sources

Failure to avoid: active feeds and roadmap-only feeds are mixed together.

Pass condition: Used in scans, Global context, Needs adapter, and License blocked buckets.

Ask

Failure to avoid: opaque AI answer becomes the product.

Pass condition: Ask is only available with selected evidence and cites exactly what it used.

Event Tracking Taxonomy

Events are redacted, low-cardinality, and product-behavior focused. File contents, tokens, keys, prompts, and uploaded text are never emitted.

route_view

Route, page family, viewport class.

upload_started

File extension and size bucket only.

upload_rejected

Reason bucket: unsupported, oversized, parse_failed.

scan_started

Input mode and ecosystem count bucket.

scan_completed

Verdict counts, source counts, elapsed bucket.

result_bucket_opened

blocked, review, unknown, pass, source lane.

package_evidence_opened

Ecosystem, verdict bucket, source lane count.

source_opened

Source family, coverage state, target type.

proof_exported

JSON or Markdown, package count bucket.

ask_opened_from_evidence

Selected evidence type and verdict bucket.

Agent Frontend Prototype Brief

Use this as the implementation prompt for the live frontend rewrite. The agent should change production code only after it can prove the current behavior with route, upload, click-path, keyboard, and evidence-pack checks.

Build the primary scan journey first.

Home and scan pages share one upload component. Drag/drop, click upload, keyboard upload, package lookup, and proof export use the same state model and event taxonomy.

Make evidence paths explicit.

Every result card opens a detail panel with registry status, live evidence lanes, source freshness, primary-source links, and a plain-English next action.

Keep Ask scoped and after inspection.

Ask is an explanation layer over selected evidence. It should not replace package verdicts, freshness clocks, source coverage, or exportable proof.

Instrument without collecting sensitive content.

Track route, file type, size bucket, verdict counts, opened evidence lanes, and exported proof format. Never track uploaded file contents, package manager auth tokens, prompts, secrets, or raw dependency text.

Copyable implementation prompt

Implement the Publicus AI-native scan-first frontend from /docs/product-redesign/.
Keep the existing static HTML, CSS token, and vanilla JS architecture.
Do not change backend API contracts.
Start with home and /scan only.
Use one shared upload/result state model.
Every hoverable card must navigate, expand, or lose hover styling.
Unknown must be classified: outside_registry, unpinned, unsupported, partial, unavailable, adapter_needed, or license_blocked.
Ask appears only after selected evidence exists.
Emit only redacted PublicusEvents with documented low-cardinality fields.
Prove with route tests, upload E2E, evidence drilldown, proof export, keyboard path, and visual QA screenshots.

Performance And Real-Behavior Gates

LCP

Target under 2.5s on production route smoke.

INP

Target under 200ms for upload, filter, detail selection, and export interactions.

CLS

Target under 0.1; evidence panels must reserve space or transition predictably.

Interaction	Measurement	Failure action
Upload file	Time from file selection to visible scanning state.	Inline progress state before network work starts.
Show results	Time from API response to first visible verdict bucket.	Render summary before long evidence lists.
Open evidence detail	Interaction latency and layout shift.	Reserve detail panel space or use in-flow mobile expansion.
Export proof	Click to browser download start.	Keep export client-side from existing scan payload.

Use native browser performance APIs and Playwright product-flow checks before adding new measurement dependencies.

Current Tech Stack Map

Backend

PythonFastAPIPydantic v2Click CLIPostgres projection

Frontend

Static HTMLCSS tokensVanilla JSIndexedDBPublicusEvents

Verification

pytestruffPlaywrightdogfooddocs audit

Implementation Gates

Gate	What changes	Proof
Artifact complete	This HTML contains user flows, wireframes, clickable states, MOMS critique, event contract, and build prompt.	Docs route tests, public page audit, and browser smoke.
Shell and IA	Navigation, page hierarchy, docs routing, one primary scan path.	Docs route tests and no duplicate shell patterns.
Scan results	Fix-first cards, classified unknowns, evidence drilldowns.	Manifest upload E2E and evidence-pack assertions.
Source coverage	Four buckets and clear primary-source actions.	Source contract route and click-path smoke.
Tracking and performance	Redacted events and native performance observation.	Unit checks plus live product-flow smoke.
Accessibility	Focus states, keyboard upload, status messages, mobile collapse.	Playwright route checks and visual QA artifacts.

Research Inputs

WCAG 2.2 for accessibility requirements.
Interaction to Next Paint for interaction performance.
Playwright best practices for user-visible E2E verification.
OSV.dev, OpenSSF Scorecard, and CISA KEV for source-backed evidence posture.