olek/AI_template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation to align terminology, clarify project stages, and improve consistency; add RECOMMENDATIONS.md for project-specific guidance.

Browse Source
This commit is contained in:
olekhondera
2025-12-12 01:50:38 +02:00
parent 8794e74934
commit 5053235e95
12 changed files with 102 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/frontend/FRONTEND_ARCHITECTURE_PLAN.md
View File

@@ -1,27 +1,27 @@
# Frontend Architecture Plan — Accounting AI Agent
# 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
> **Sources:** Next.js App Router best practices (per latest docs), product/domain docs in `/docs`
## 0. Goals & Non-Goals
- Ship a clear, predictable frontend for finance users: fast tables, reliable status, explainability (rule hit, embedding score, LLM reasoning trace).
- Optimize for multi-tenant, webhook-driven states, and Stripe-hosted billing; no direct provider/LLM calls from the browser.
- 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.
- 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: `/`, `/transactions`, `/transactions/review`, `/rules`, `/reports`, `/settings/billing`, `/settings/accounts`, `/settings/team`.
- Minimal routes: `/`, `/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, transactions, approvals, rules, reports, billing, settings
entities/ # tenant, user, transaction, rule, report, event, integration
shared/ # ui kit, hooks, api client, lib (formatting, currency), auth client
features/ # onboarding, records, approvals, rules, reports, billing, settings
entities/ # tenant, user, record, rule, report, event, integration
shared/ # ui kit, hooks, api client, lib (formatting, domain utils), auth client
widgets/ # composed UI blocks (dashboards, charts, tables)
```
- Co-locate queries/mutations/types/tests per feature; keep shared minimal.
@@ -29,7 +29,7 @@ src/
## 3. Data Layer & State
- HTTP client with typed fetchers; attach auth/tenant context; central 401/403 handling.
- React Query/SWR for cache + background refresh; server-side data where possible (RSC) with client wrappers for interactivity.
- Pagination/virtualization for large lists (`/transactions`, `/events`); filters persisted in URL search params.
- Pagination/virtualization for large lists (`/records`, `/events`); filters persisted in URL search params.
- Optimistic updates only for low-risk actions (naming/rule toggles); approvals/overrides stay pessimistic with clear status.
## 4. Auth, Tenant, Roles
@@ -38,12 +38,12 @@ src/
- Role-based UI gating (owner/admin/viewer); hide/disable disallowed actions.
## 5. UX for Key Flows
- **Transactions:** table with status chips (ingested/categorized/needs_approval/approved/error), drawer: raw payload, rule hit, embedding score, `reasoning_trace`, receipts, history.
- **Records:** table with status chips (ingested/categorized/needs_approval/approved/error), drawer: raw payload, rule hit, embedding score, `reasoning_trace`, attachments, history.
- **Approvals:** queue view, approve/override with confirmation; optional rule creation inline; show impact preview.
- **Rules:** list (priority, hit rate), editor with condition/action JSON preview, test on sample set.
- **Reports:** date range, currency/timezone indicators; async export with status chips and download links.
- **Billing:** Stripe-hosted Checkout/Portal; post-return state from backend; recovery CTAs.
- **Integrations:** QuickBooks/bank connection status, webhook health, rotate secrets; surface retry guidance.
- **Reports:** date range and domain indicators (e.g., timezone/currency if relevant); async export with status chips and download links.
- **Billing:** payment‑provider‑hosted Checkout/Portal; post-return state from backend; recovery CTAs.
- **Integrations:** external provider connection status, webhook health, rotate secrets; surface retry guidance.
- **Errors/Support:** human-readable errors with traceId; recovery steps for webhook/LLM failures.
## 6. Styling & UI Kit
@@ -71,12 +71,12 @@ src/
## 11. Testing
- Unit: helpers/formatters.
- Component: transactions table/drawer, approvals flow, rule editor, billing/status banners.
- E2E: onboarding + source connect, transaction ingest display, categorize → approve, rule create/apply, billing flow, report export.
- Component: records table/drawer, approvals flow, rule editor, billing/status banners.
- E2E: onboarding + source connect, record ingest display, categorize → approve, rule create/apply, billing flow, report export.
## 12. Open Questions / To Finalize
- Exact table virtualization lib (if any) and charting choice.
- How much data is loaded server-side vs client-side for `/transactions` (depends on API paging).
- How much data is loaded server-side vs client-side for `/records` (depends on API paging).
- Error surface for LLM fallback (what to show vs hide).
- i18n scope (English only vs multi-lingual).
- Whether to expose `rawSnippet` of LLM response in UI or keep to audit logs only.