feature-ux-spec · supabase_json
KnowledgeVault AI feature-ux-spec
feature-ux-spec artifact · for KnowledgeVault AI · status approved
open questions
No items captured.
Agent Handoff
Start Here
feature-ux-spec artifact · for KnowledgeVault AI · status approved
Completion Evidence
No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.
Open Questions
No section body captured.
Structured Payload
Machine-readable source fields
phase
id
main
name
KnowledgeVault AI v1
status
approved
features
| id | ux | name | functional |
|---|---|---|---|
| F-01 | - flows: 1 item - platform: mobile - surfaces: 3 items - design tokens: 4 items - open questions: 0 items | Expert Onboarding & Registration | - why: Cold-start acquisition — retiring experts must register and connect a payout account with zero writing and zero tech friction. If onboarding fails no captures happen. - today: No signup flow. experts table empty. No Stripe Connect accounts. - target: Expert visits /experts/signup, submits name/email/phone/role_type/specialties/years_experience. POST /api/experts/signup creates expert record and Stripe Connect Express account, returns stripe_onboarding_url. Expert redirected to Stripe for bank connection. On return, confirmation screen shown. - done when: 7 items - scenarios: 3 items - c |
| F-02 | - flows: 1 item - platform: mobile - surfaces: 2 items - design tokens: 4 items - open questions: 0 items | Expert Product Queue | - why: Experts need a curated, prioritized list of SKUs matching their specialty so they spend capture time on high-value knowledge-gap products. - today: No product queue endpoint or UI. products table and experts.specialties[] exist per blueprint schema. - target: GET /api/products/queue returns products filtered by expert.specialties[] (matching products.category), ordered has_surge_badge DESC then coverage_pct ASC. is_fully_captured=true excluded. Each result: id, sku, name, manufacturer, has_surge_badge, coverage_pct, earnings_potential {min, max}. - done when: 8 items - scenarios: 3 item |
| F-03 | - flows: 1 item - platform: mobile - surfaces: 2 items - design tokens: 4 items - open questions: 0 items | Voice Capture Session | - why: Voice-first capture is the core product differentiator. Experts contribute without writing. GPT-4o extracts tacit knowledge via AI follow-up questions. Real-time structuring panel proves value to the expert as they speak. - today: No capture session endpoint or UI. product_pre_seeds table exists per blueprint. - target: Expert taps START. POST /api/sessions/start creates CaptureSession, loads pre-seed cache, returns session_id and first_question. Expert answers by voice — Deepgram Nova-2 streams to transcript. POST /api/sessions/:id/audio returns transcript_segment, micro_objects_extrac |
| F-04 | - flows: 1 item - platform: mobile - surfaces: 2 items - design tokens: 3 items - open questions: 0 items | Session Evaluation & Scoring | - why: AI-evaluated quality scores make the payment model economically viable. Ground-truth gate prevents gaming and ensures safety claims are accurate. - today: No evaluation pipeline. capture_sessions table exists per blueprint. - target: After POST /api/sessions/:id/complete, SharedExpertContext serialised and pushed to evaluation queue within 5s. o3 scores all 7 dimensions (technical_accuracy 0.30, completeness 0.20, practicality_tacit_insight 0.15, safety_compliance 0.15, clarity_structure 0.10, novelty 0.05, brevity_efficiency 0.05). Ground-truth gate runs in parallel for flagged terms. |
| F-05 | - flows: 1 item - platform: mobile - surfaces: 1 item - design tokens: 4 items - open questions: 0 items | Expert Earnings & Payouts | - why: Experts must trust the platform to pay correctly and transparently. Visible earnings history with breakdown, correct hold timing, and reliable Stripe payouts are the foundation of expert retention. - today: No earnings endpoint or UI. payments table exists per blueprint. - target: GET /api/experts/:id/earnings returns total_earned, pending, sessions[]. pg_cron releases pending_release payments hourly when hold_until<=now(). Stripe Connect transfer initiated. Stripe webhook transfer.paid updates status to paid. Push notification sent on session scored and on payment released. - done when |
| F-06 | - flows: 1 item - platform: both - surfaces: 2 items - design tokens: 4 items - open questions: 0 items | Knowledge Retrieval (Semantic Search) | - why: Field technicians need instant accurate answers from expert knowledge. Semantic search surfaces the right chunk within seconds of a natural-language query. - today: No query endpoint or UI. knowledge_chunks table with vector(1536) exists per blueprint. - target: Company-authenticated POST /api/query embeds query via text-embedding-3-small (1536d), runs pgvector cosine similarity search against knowledge_chunks WHERE is_published=true, ranks by (cosine_similarity×0.7)+(ground_truth_verified::int×0.2)+(novelty_score×0.1), returns top-5 with expert attribution and verified badge. field_ver |
| F-07 | - flows: 1 item - platform: both - surfaces: 2 items - design tokens: 4 items - open questions: 0 items | Virtual Expert Query | - why: Field technicians query a named expert persona directly — not a generic knowledge base. This drives trust and the emotional hook that retiring experts never really leave. - today: No Virtual Expert query endpoint or UI. virtual_experts table exists per blueprint. Published after session_count>=3 AND avg_accuracy_score>=70. - target: Company-authenticated GET /api/virtual-experts returns is_published=true experts. POST /api/virtual-experts/:id/query scopes to knowledge_chunks WHERE expert_id=virtual_expert.expert_id AND is_published=true. Top-3 chunks passed to GPT-4o with synthesis prom |
| F-08 | - flows: 1 item - platform: web - surfaces: 1 item - design tokens: 6 items - open questions: 0 items | Company Coverage Dashboard | - why: Operations managers need to see knowledge coverage at a glance. Primary value-proof surface for buyer retention. Must load under 2 seconds for demo on a projected screen. - today: No dashboard endpoint or UI. companies, company_knowledge_access, field_queries tables exist per blueprint. - target: GET /api/dashboard/company/:id returns coverage_grid, top_queries, slang_cloud, stats from materialized view — no vector queries. Demo mode: company_id=demo, no auth, seed data. Powered-by badge on dashboard. - done when: 8 items - scenarios: 2 items - constraints: 6 items - error states: 3 ite |
| F-09 | - flows: 1 item - platform: web - surfaces: 1 item - design tokens: 4 items - open questions: 0 items | Platform Analytics Panel | - why: Analytics panel closes the demo loop — executives see aggregate impact and platform efficiency. OQ-1 resolved: cost-per-session, cost-per-chunk, and total session cost shown in analytics panel. - today: No analytics endpoint or UI. GET /api/analytics/platform defined in blueprint but not implemented. - target: Admin-authenticated GET /api/analytics/platform returns hours_preserved, expert_count, chunk_count, verified_chunk_count, support_reduction_pct, cost_per_session, cost_per_chunk, total_session_cost. AI API costs (Deepgram, GPT-4o, o3, embedding) logged in capture_sessions.cost_bre |
cross cutting
auth pattern
Two auth roles. Expert: Supabase Auth JWT role=expert — required for /api/experts/*, /api/sessions/*, /api/products/queue. Company: Supabase Auth JWT role=company, company_id claim — required for /api/query, /api/virtual-experts/*, /api/dashboard/*. No anonymous mode (OQ-8 resolved). Unauthenticated requests return 401. Exception: GET /api/dashboard/company/demo returns public seed data without JWT.
data contracts
Expert
id
uuid
bio
string|null
name
string
role type
string
specialties
string[]
years experience
integer|null
stripe account id
string|null
Payment
id
uuid
status
pending_release|released|paid|payment_hold|disputed
expert id
uuid
hold until
timestamptz|null
session id
uuid
base amount
decimal
surge bonus
decimal
rarity bonus
decimal
total amount
decimal
completion bonus
decimal
quality multiplier
float
Product
id
uuid
sku
string
name
string
category
string|null
image url
string|null
coverage pct
float — count(completed_sessions)/target_session_count per OQ-7
manufacturer
string
has surge badge
boolean
is fully captured
boolean
VirtualExpert
id
uuid
name
string
expert id
uuid
description
string|null
is published
boolean
session count
integer
avg accuracy score
float|null
knowledge chunk count
integer
KnowledgeChunk
id
uuid
sku
string
content
string
expert id
uuid
chunk type
failure_mode|symptom|fix|psi_range|safety_warning|field_tip|tool_required|part_number_reference
product id
uuid
session id
uuid
is published
boolean
novelty score
float|null
ground truth verified
boolean
error envelope
{"error": "<message>", "code": "<slug>", "status": <int>}. All API errors. Client handles 400, 401, 403, 404, 409, 422, 429, 500. 429 includes Retry-After header.loading pattern
Skeleton screens shown immediately on navigation. Skeleton matches layout of loaded state. 10s timeout shows error with retry CTA. No spinner-only states.
empty state pattern
Every list/grid has an empty state: icon + headline (<=6 words) + body (<=20 words) + CTA when actionable. Never a blank screen.
open questions
No items captured.
schema version
1.0