Add foundational documentation templates to support product design and architecture planning, including ADR, archetypes, LLM systems, dev setup, and shared modules.
This commit is contained in:
olekhondera
@@ -1,26 +1,30 @@
|
||||
# Frontend Architecture Plan — AI Product Template
|
||||
|
||||
> **Status:** Phase 0 (Planning) — recommendations to finalize in Phase 1
|
||||
> **Scope:** Next.js (App Router, TS) + Tailwind + React Query/SWR for ingestion → categorization → approvals → reporting → billing
|
||||
> **Scope:** Next.js (App Router, TS) + Tailwind + React Query/SWR. The concrete flows (chat, generation, pipeline, approvals, billing) depend on the chosen archetype in `/docs/archetypes.md`.
|
||||
> **Sources:** Next.js App Router best practices (per latest docs), product/domain docs in `/docs`
|
||||
|
||||
> **Purpose:** This file is a scratchpad for exploring options and trade‑offs.
|
||||
> Move finalized decisions into `/docs/frontend/architecture.md`.
|
||||
> **Archive or delete this plan after Phase 1** to avoid duplication.
|
||||
|
||||
## 0. Goals & Non-Goals
|
||||
- Ship a clear, predictable frontend for users in your target domain: fast tables, reliable status, explainability (rule hit, embedding score, LLM reasoning trace).
|
||||
- Optimize for multi-tenant, webhook-driven states, and payment‑provider‑hosted billing; no direct provider/LLM calls from the browser.
|
||||
- Ship a clear, predictable frontend for your chosen archetype: fast core interactions (chat/workflow/pipeline/automation), reliable status, explainability when applicable (scores, traces, source).
|
||||
- Optimize for long‑running or webhook‑driven states if your product uses them; no direct provider/LLM calls from the browser.
|
||||
- Non-goal: custom card forms or direct provider SDKs in the browser.
|
||||
|
||||
## 1. Routing & Layout
|
||||
- App Router with `app/`; root `layout.tsx` imports globals (per Next.js docs).
|
||||
- Layout shells: public (marketing), app shell (auth/tenant-protected), auth screens.
|
||||
- Minimal routes: `/`, `/records`, `/records/review`, `/rules`, `/reports`, `/settings/billing`, `/settings/integrations`, `/settings/team`.
|
||||
- Minimal routes depend on archetype. Example for pipeline products: `/`, `/records`, `/records/review`, `/rules`, `/reports`, `/settings/billing`, `/settings/integrations`, `/settings/team`.
|
||||
- Navigation state from `next/navigation`; avoid dynamic `href` objects in `<Link>` (App Router requirement).
|
||||
|
||||
## 2. Feature/Folder Structure
|
||||
```
|
||||
src/
|
||||
app/ # routes/layouts
|
||||
features/ # onboarding, records, approvals, rules, reports, billing, settings
|
||||
entities/ # tenant, user, record, rule, report, event, integration
|
||||
features/ # archetype flows (e.g., onboarding, chat, items, approvals, reports, billing, settings)
|
||||
entities/ # domain entities (tenant/user optional; items/messages/drafts/tasks, etc.)
|
||||
shared/ # ui kit, hooks, api client, lib (formatting, domain utils), auth client
|
||||
widgets/ # composed UI blocks (dashboards, charts, tables)
|
||||
```
|
||||
|
||||
@@ -13,7 +13,10 @@
|
||||
- `/docs/frontend/ui-ux-guidelines.md`
|
||||
---
|
||||
|
||||
> Recommendations for Phase 0. Lock decisions in Phase 1.
|
||||
> Recommendations for Phase 0. Lock decisions in Phase 1.
|
||||
> After Phase 1, this file is the **canonical record of locked frontend architecture decisions**.
|
||||
> Use `FRONTEND_ARCHITECTURE_PLAN.md` for working notes and archive/delete it after Phase 1.
|
||||
> Modules like records/rules/approvals/billing are **examples for one archetype**. Rename or omit per `/docs/archetypes.md`.
|
||||
|
||||
## 1. Stack
|
||||
- Framework: Next.js (App Router) + TypeScript.
|
||||
|
||||
@@ -12,17 +12,18 @@
|
||||
---
|
||||
|
||||
## 1. Role of Frontend
|
||||
- Deliver onboarding, data connection, categorization review, approval, reporting, and optional billing experiences for users in your target domain.
|
||||
- Keep flows fast, explainable (surface reasoning trace, rule hit), and safe (reflect webhook/provider states, avoid double actions).
|
||||
- Deliver the primary user experience for your chosen archetype (chat, generation workflow, pipeline review, automation dashboard) plus onboarding/settings and optional billing.
|
||||
- Keep flows fast, explainable (surface reasoning traces/scores when used), and safe (reflect provider states, avoid double actions).
|
||||
|
||||
## 2. Core Screens & Flows
|
||||
- Marketing/landing with CTA to signup.
|
||||
- Onboarding: signup/login, plan selection (payment provider Checkout/Portal if applicable), source connection (external providers via OAuth2/webhooks), team invites.
|
||||
- Records: lists/filters, detail drawer (raw fields, rule hit, embedding score, LLM reasoning trace), bulk actions.
|
||||
- Approvals & Rules: approval queue, override + optional rule creation, rule list/editor, history snippets.
|
||||
- Reports: dashboards/summaries, exports with statuses.
|
||||
- Billing & Settings: subscription status, payment method, tenant/team management, integrations health, audit/event log view.
|
||||
- Routes (min set): `/`, `/records`, `/records/review`, `/rules`, `/reports`, `/settings/billing`, `/settings/integrations`.
|
||||
- Core screens depend on the chosen archetype (see `/docs/archetypes.md`).
|
||||
Example for pipeline products:
|
||||
- Marketing/landing with CTA to signup.
|
||||
- Onboarding: signup/login, plan selection (provider Checkout/Portal if applicable), source connection (OAuth2/webhooks), team invites.
|
||||
- Items/records: lists/filters, detail drawer (raw fields, scores, LLM reasoning trace), bulk actions.
|
||||
- Human review (optional): approval/override UI, optional rules/policies editor.
|
||||
- Reports (optional): dashboards/summaries, exports.
|
||||
- Billing & Settings (optional): subscription status, payment method, tenant/team management, integrations health, audit/event log view.
|
||||
|
||||
## 3. Technical Principles
|
||||
- Next.js (App Router) with TypeScript; Tailwind for styling; React Query/SWR for data fetching and cache orchestration.
|
||||
|
||||
@@ -11,6 +11,8 @@
|
||||
- `/docs/backend/payment-flow.md`
|
||||
---
|
||||
|
||||
> This guide reflects a **pipeline / human‑review** archetype. For chat‑first or generation tools, keep the same principles (clarity, accessibility, safe actions) but replace the concrete flows and terminology per `/docs/archetypes.md`.
|
||||
|
||||
## 1. Tone & Clarity
|
||||
- Professional and concise. Emphasize trust (audit log, reasoning traces, secure billing and webhooks).
|
||||
- Avoid jargon without tooltips; show why a decision was made (rule hit, similarity, LLM reasoning).
|
||||
|
||||
Reference in New Issue
Block a user