86 lines
4.5 KiB
Markdown
86 lines
4.5 KiB
Markdown
# 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`.
|