template-showcase/README.md

ConusAI Showcase

Notes with attachments on Postgres and Blob Storage, audited, observed and metered: every ConusAI SDK in one Next.js app built with Feature-Sliced Design (showcase plan D11). The template is proven in this repository by scripts/vendor/test-template.sh at the same commit as the SDKs it uses (D18).

Pinned versions

Pinned on 2026-10-06 with npm view <package> version (showcase §2.7):

Package	Version
next	16.3.8
react, react-dom	19.3.0
typescript	5.9.3 (5.x: the @conusai-sdk/plugin peer requires ^5)
drizzle-orm, drizzle-kit	0.45.3, 0.31.11
postgres	3.4.9
zod	4.6.5
server-only	0.0.1
vitest	5.0.3
eslint, eslint-config-next, @eslint/eslintrc	9.39.5 (ESLint 10 breaks the React plugin bundled by eslint-config-next), 16.3.8, 3.3.7
steiger, @feature-sliced/steiger-plugin	0.7.0, 0.8.0
@playwright/test	1.63.0
@types/node, @types/react, @types/react-dom	26.6.4, 19.3.0, 19.3.0

The @conusai-sdk/* packages are not listed: test-template.sh installs them from the bundle built from this commit.

Layout

• app/ routes only; each file re-exports from src/views or src/app.
• src/app, src/views, src/widgets, src/features, src/entities, src/shared: the FSD layers, imports point downward only (checked by steiger).
• src/shared/config/env.ts: the environment, parsed once with zod (D12).
• src/shared/api/*/server.ts: server-only SDK clients (server-only).
• src/shared/lib/visitor.ts: the signed sc_vid visitor cookie (D16).

What each slice demonstrates

Slice	Demonstrates
features/create-note	A note in Postgres, audited as note.created; NATS announces it and Qdrant indexes it when those are linked.
features/edit-note, features/delete-note	Writes scoped to the author, each audited (note.updated, note.deleted).
features/upload-file, features/delete-file	Attachments in Blob Storage, one usage event per upload with an idempotency key; a per-minute quota when KV is linked.
features/publish-note-event	An author re-announces a note on NATS (note.announced in the audit log); another visitor is refused.
features/search-notes	Similar-note search in Qdrant, when Qdrant is linked.
features/export-notes	The visitor's notes written as one JSON object to the dedicated S3 bucket, when S3 is linked.
features/rate-limit	The uploads left this minute, read from KV, when KV is linked.
features/simulate-traffic	A scripted visitor journey that produces observed page views, a started journey and an error.
widgets/note-list, widgets/attachments	The visitor's notes and their attachments, with the controls each feature provides.
widgets/audit-timeline, widgets/usage-meter	The platform's audit events for this project, and the visitor's metered uploads and bytes.
widgets/enable-card, widgets/module-panel	One slot per optional module: its feature when linked, its enable card (text from the platform's catalog) when not (D13).
views/dashboard, views/audit, views/platform	The composed pages; the platform page lists each optional service as linked or not.

Optional modules

The showcase reads the variables the platform injects for each linked service (D8, D13). A module without its variables shows its enable card instead of its feature. Its variables are REDIS_URL (KV), NATS_URL and NATS_TOKEN, QDRANT_URL and QDRANT_API_KEY, GIT_URL, and AWS_ENDPOINT_URL, S3_BUCKET, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. The S3 names are the ones the platform injects for an S3 service.

Commands

• npm run typecheck, npm run steiger, npm run lint, npm test, npm run build
• npm run e2e runs the Playwright suite against a production build. It starts e2e/fake-platform.mjs in place of the platform and withholds the optional module variables, so every enable card shows. The suite covers creating a note and its audit entry, an attachment moving the usage meter, the enable cards, axe (no serious or critical issues on each page) and the Core Web Vitals budgets (LCP at most 2.5 s, INP at most 200 ms) measured in Chromium.
• npm test also runs src/shared/lib/optional.live.test.ts against live NATS, Qdrant and S3 when NATS_URL, QDRANT_URL and AWS_ENDPOINT_URL are set; without them it is skipped.
• bash scripts/vendor/test-template.sh from the repository root runs all of them against the bundle; bash scripts/vendor/test-template.sh --e2e adds the Playwright suite.