AI_template/docs/content-structure.md

App & Content Structure (Template)

---

Last Updated: 2025-01-17
Phase: Phase 0 (Planning)
Status: Draft
Owner: Product, UX/UI
References:

• /docs/project-overview.md (product vision)
• /docs/frontend/ui-ux-guidelines.md (UX patterns)
• /docs/backend/api-design.md (API resources)

---

Structure of key screens/flows for a generic AI‑assisted product. Use this as a template and adapt to your domain.

General Principles

• Web-first (desktop + mobile web); clear, concise copy for target users in your domain.
• Emphasize trust: audit trail, optional reasoning traces, secure webhooks, role-based access, provider-hosted billing.
• Keep flows short; surface provider states (webhook-driven) and recovery steps.

1. Marketing / Landing (lightweight)

• Hero: what the product does (ingestion, processing/classification, approvals, reporting), security/billing note, CTA to start.
• How it works: 3–4 steps (connect, ingest, process, approve/report).
• Integrations: external providers (OAuth2/webhooks), LLM helper.
• Pricing: plans via provider-hosted billing (if applicable), trial info.
• FAQ and compliance/audit cues.
• CTA: “Start” → signup flow.

2. Onboarding & Tenant Setup

• Create account/tenant; select plan (provider-hosted checkout/portal); invite teammates.
• Connect data sources: OAuth2 to external providers, webhook URL display.
• Confirm webhooks/health; show status and retry guidance.

3. Records & Processing

• Records list with filters (date, source, status: ingested, processed, needs_approval, approved, failed).
• Detail drawer: raw fields, matched rule/embedding score, LLM reasoning_trace, history, related attachments.
• Bulk actions: reprocess, send to approval, archive (if allowed).

4. Approvals & Rules

• Approval queue: items requiring human review; assign/reassign; batch approve.
• Override outcome with optional rule creation (scope, conditions, action); preview impact/safety notes.
• Event log snippet (who/what/when, source_agent).

5. Rules Management

• Rules list (name, priority, hit rate, last updated, enabled/disabled).
• Rule editor: conditions (source fields, ranges, text, embedding similarity tag), actions (labels/categories/tags), evaluation order.
• Test/preview on a sample set before saving.

6. Reports & Exports

• Dashboards and summaries; time range + tenant/source filters.
• Export (CSV/PDF) with clear timezone/currency notes where relevant.
• Status and history of generated reports; link to underlying events.

7. Billing & Settings

• Subscription status (provider), plan details, payment method update via portal.
• Tenant/team management: roles, invites, revocations.
• Integrations: connection health, webhook secrets, rotate keys.
• Audit log (EventLog) with source_agent and filters.

8. Support & Logs

• Surface recent events (/api/events feed) for downstream agents and debugging.
• Troubleshooting tips (webhook mismatch, ingestion failures, LLM fallback errors), retry buttons where safe.
• Links/contact for support.