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