AI_template/docs/project-overview.md

Project Overview: Starter Template (Provider‑agnostic)

---

Phase: Phase 0 (Planning) Status: Draft Owner: Product Team References:

• /docs/phases-plan.md (development roadmap)
• /docs/content-structure.md (app/screen structure)

---

1. Project Goal

Provide a universal starting point for new products that leverage AI assistance. The template outlines how to structure documentation and technical decisions for different AI product archetypes (chat assistants, generation tools, pipelines, agentic automation, internal tools).
Capabilities such as integrations/ingestion, staged processing (rules/embeddings/LLM), human review, reporting, multi‑tenancy, and billing are optional modules you can mix & match.

Emphasis areas: trust (auditability, optional reasoning traces), speed (near‑real‑time processing), and clarity (human approvals and transparent reporting), adaptable to your domain.

First step: choose an archetype and modules in /docs/archetypes.md, then tailor the rest of this document.

2. Target Audience

• Define your primary users and stakeholders for the target domain.
• Typical teams value:
  • automation with explainability (reasoning traces and event logs);
  • reliability (idempotent ingestion, safe retries);
  • compliance (audit trail, role‑based access).

3. Unique Value Proposition

1. Clear AI interaction surface
   Chat, workflow UI, batch pipeline, or API — with optional explainability (reasoning_trace) and trace IDs.
2. Optional human feedback loop
   Approvals/overrides, edits, ratings, or escalation — all actions audited (EventLog, source_agent).
3. Optional integrations & ingestion
   OAuth2/webhooks/files/SDKs; idempotent handling and safe retries.
4. Optional reporting & billing
   Dashboards/exports and provider‑hosted subscriptions/usage if your product needs them.
5. Security by design (single‑ or multi‑tenant)
   Tenant isolation and RBAC when applicable; webhook verification and audit logging for all products.

4. Key Features (example template)

4.1. Onboarding & Integrations (optional)

• User/tenant signup/login if your product needs accounts.
• Connect external data sources (OAuth2, webhooks, file uploads, etc.) if you ingest data.
• Configure subscription/billing if applicable.
• Example domain model for pipeline products: Tenant, User, Record, Rule, Attachment, Report, EventLog, Embedding; EventLog.source_agent, Record.reasoning_trace JSONB.
  Rename or replace with your domain entities for other archetypes (messages, drafts, tasks, etc.).

4.2. Ingestion

• Webhooks/workers normalize provider payloads into a unified schema (if you have ingestion).
• Idempotent writes; deduplication; INGESTED events with source_agent.

4.3. Classification/Processing

• If you use staged processing: rules/heuristics → embeddings/RAG → LLM fallback via callLLM().
• Optionally persist reasoning_trace JSONB on items; log PROCESSED (or similar).

4.4. Approval & Rules

• UI for reviewing/overriding outcomes; edits/ratings; optional rule creation from overrides (if relevant).
• Log APPROVED, RULE_CREATED; track who/when/why.

4.5. Reporting & Events

• Dashboards and exports per tenant.
• Read‑only /api/events for downstream agents and observability.

4.6. Billing & Access

• Subscriptions via a payment provider; tenant‑scoped roles.
• Audit log (EventLog) with source_agent.

5. Non‑Functional Requirements (High‑Level)

• Reliability: idempotent ingestion/webhooks, durable queues, retries, monitoring.
• Security: RBAC per tenant, webhook signature verification, secret management, audit/event logging; no raw card data stored.
• Performance: near real‑time processing and acceptable latency for human approvals; fast UI for lists/filters.
• Explainability: every automated decision includes reasoning_trace; events logged with source_agent.
• Localization: primary UI in English; other locales optional.
• Operational tooling: queue-based pipelines (BullMQ + Redis) with observability and dead-letter handling for ingestion/categorization/reporting jobs.

6. Constraints and Assumptions

• Web-first product (desktop + mobile web). Native apps not in scope for V1.
• Payments via a provider; exact choice is project‑specific.
• LLM calls should go through a single abstraction to swap models easily.
• Multi‑agent readiness: consider EventLog.source_agent and optional reasoning_trace.