Marvia-11
Analyze once. Present everywhere.
Extensions produce structured Findings. The report engine turns them into consistent, explainable reports — it never crawls, parses or snapshots anything.
Finding schema
1.0
Report sections
8
Finding categories
7
Export formats
6
Report pipeline
Report first
Report usability outranks raw data completeness.
Schema driven
Reports render from versioned schemas, never from bespoke markup.
Component driven
Only design-system components are used to render a report.
Extension ready
Extensions contribute Findings and nothing else.
Versioned
Schema, report and extension versions are tracked on every render.
Manual refresh
Reports update on explicit user action, never by silent polling.
Visual first
Metrics and Findings are visually intuitive before they are exhaustive.
Explainable
AI produces summaries, strategies and priorities for every report.
Export ready
PDF, Markdown, JSON and CSV are first-class outputs.
Findings
The smallest unit of insight
Every extension emits Findings and nothing else: metadata, content and context — structured, scored and traceable to its source extension.
{
"schemaVersion": "1.0",
"id", "category", "type", "severity", "priority", "status",
"confidence", "tags", "sourceExtension", "createdAt",
"content": { "title", "summary", "description", "evidence", "recommendation" },
"context": { "affectedObjects", "metadata", "aiNotes" }
}Rules
- · Extensions output Findings only — no HTML and no custom UI.
- · A Finding is the smallest unit of insight and is always self-describing.
- · Evidence is structured data; raw HTML never reaches the renderer.
- · Every Finding carries a confidence score so AI ranking stays honest.
Severity · Priority · Status
Evidence kinds
| Category | Examples |
|---|---|
| seo | Metadata, links, images |
| performance | Load times, Core Web Vitals |
| accessibility | ARIA, contrast, keyboard navigation |
| security | Tracking, advertising, vulnerabilities |
| content | Localization, brand alignment |
| ai | Automated insights and recommendations |
| custom | Extension-specific categories |
Insight engine
Grouped, scored, explainable
Findings are grouped once, then reused by the report, the dashboard and the AI. No extension renders UI directly.
overview
Counts, category spread and the derived health score.
highlights
What is already correct — success findings.
opportunities
Improvements that are not yet failures.
risks
Critical or urgent findings that need action now.
recommendations
Findings carrying structured guidance.
summary
A single explainable sentence for humans and AI.
AI consumes
AI generates
Structure & registry
Eight sections, always in this order
Report types register dynamically, but the section order is fixed so every report in Marvia reads the same way.
| # | Section | Contains | Permission |
|---|---|---|---|
| 1 | Header | Workspace, project, website, extension, version, generated at | — |
| 2 | Executive summary | Business, technical and strategic impact | — |
| 3 | Metrics | Visual cards, badges and charts | — |
| 4 | Findings | Grouped by category and severity | — |
| 5 | Recommendations | Prioritized, actionable guidance | — |
| 6 | History | Snapshot comparison and rollback | report.history |
| 7 | Learning | Lessons and playbooks linked to each finding | — |
| 8 | Actions | Refresh, export, share and AI explanation | report.actions |
Registry rules
- · Report types, schemas and components register at runtime.
- · A registration declares its permission, widgets and export formats up front.
- · Section order, visibility and responsive rules live in the schema, not in components.
Comparison & history
- · Every generation is recorded with snapshot, report and extension versions.
- · Generation time, generator and duration are stored for SLA tracking.
- · Rollback restores a previous report version without regenerating findings.
Page states
- · Report generation stays under 2s for 100 findings.
- · Rendering is streamed section by section; findings never block the header.
- · Sensitive sections are permission-gated before data is fetched, not after.
SDK & export
What an extension may call
Seven methods, findings in, presentation owned by the engine. Exports read the exact object the UI reads.
Report SDK
- createReport() — Start a report shell for a workspace subject.
- registerReport() — Publish a report type, its schema and permissions.
- registerFinding() — Contribute one structured insight.
- registerMetric() — Contribute one numeric or textual metric.
- registerSection() — Add a schema-declared section to a report type.
- registerExport() — Declare a supported export format.
- registerAction() — Expose a permission-gated action in the actions section.
- · Extensions return Findings only — no UI rendering, ever.
- · The report engine owns presentation: schema-driven, reusable, strongly typed.
- · Every SDK call is workspace-scoped and permission-checked before it takes effect.
Export engine
- pdfmvpClient-ready document with the fixed section order.
- markdownmvpPortable text for docs, tickets and AI prompts.
- jsonsupportedThe report and its findings, verbatim.
- csvsupportedFindings as rows for spreadsheets and BI.
- htmlfutureSelf-contained shareable page.
- pptxfutureSlide summary for stakeholder reviews.
- · Every export reads the same report object the UI reads — no second pipeline.
- · Sections excluded by permission are excluded from the export as well.
- · Filenames carry workspace, report kind and generation timestamp.
Integration
Learning, dashboard and what comes next
Every finding teaches; every report feeds the workspace dashboard.
Learning
- · Every Finding links to a lesson, guide or playbook for the fix.
- · Learning links are resolved from the finding type, not written by extensions.
- · Completed lessons feed workspace onboarding progress.
Dashboard
- Latest reports — Report registry, workspace-scoped
- Critical issues — Insight engine — risks group
- Opportunities — Insight engine — opportunities group
- Health score — Insight engine — overview score
Next steps
- · RBAC for sensitive report sections.
- · Schema versioning with an explicit deprecation policy.
- · PDF and Markdown export MVP.
- · Performance SLAs: report generation under 2s for 100 findings.