83 lines
4.0 KiB
Markdown
83 lines
4.0 KiB
Markdown
# Project Overview: Starter Template (Provider‑agnostic)
|
||
|
||
---
|
||
**Last Updated:** 2025-01-17
|
||
**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 projects that may include data ingestion, processing/classification (rules + embeddings + LLM), human approvals, reporting, and optional billing.
|
||
|
||
Emphasis areas: trust (auditability, optional reasoning traces), speed (near‑real‑time processing), and clarity (human approvals and transparent reporting), adaptable to your domain.
|
||
|
||
## 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. **Automated processing with explainability**
|
||
Rules + embeddings (`pgvector`) first, LLM fallback via a single helper, with optional `reasoning_trace` per record.
|
||
2. **Human‑in‑the‑loop approvals**
|
||
Review/override UI with optional rule creation; every action is logged (e.g., `source_agent`).
|
||
3. **Reliable ingestion**
|
||
OAuth2/webhooks for external providers; idempotent event handling; queue workers for retries.
|
||
4. **Reporting & optional billing**
|
||
Dashboards/exports per tenant; subscription management with tenant‑scoped access control.
|
||
5. **Multi‑tenant and secure by design**
|
||
Tenant isolation, RBAC, webhook verification, audit log (`EventLog`).
|
||
|
||
## 4. Key Features (example template)
|
||
|
||
### 4.1. Onboarding & Integrations
|
||
- Tenant signup/login (Clerk/Auth.js or equivalent).
|
||
- Connect external data sources (OAuth2, webhooks, file uploads, etc.).
|
||
- Configure subscription/billing if applicable.
|
||
- Example domain model (multi‑tenant): `Tenant`, `User`, `Record`, `Rule`, `Attachment`, `Report`, `EventLog`, `Embedding`; `EventLog.source_agent` (e.g., default value), `Record.reasoning_trace` JSONB.
|
||
|
||
### 4.2. Ingestion
|
||
- Webhooks/workers normalize provider payloads into a unified schema.
|
||
- Idempotent writes; deduplication; `INGESTED` events with `source_agent`.
|
||
|
||
### 4.3. Classification/Processing
|
||
- Rule engine first; embeddings similarity next; LLM fallback via `callLLM()`.
|
||
- Optionally persist `reasoning_trace` JSONB on records; log `PROCESSED` (or similar).
|
||
|
||
### 4.4. Approval & Rules
|
||
- UI for reviewing/overriding outcomes; optional rule creation from overrides.
|
||
- 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`.
|