# 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.