@sylphx/flow 1.0.5 → 1.1.0

package/assets/knowledge/guides/tech-stack.md

@@ -0,0 +1,92 @@
+---
+name: Tech Stack (Recommended)
+description: Opinionated stack (Next.js, PandaCSS, GraphQL, Pothos, Drizzle) - optimized for LLM accuracy
+---
+
+# Technical Stack
+
+Scalable, secure SaaS stack. Type safety, performance, serverless. Validate with E2E (Playwright), monitor with Sentry.
+
+## Domain-Driven Architecture
+
+Feature-based layout: `src/features/<domain>/` (frontend), `src/graphql/<domain>/` (backend). Colocate related code. Cross-domain via explicit exports.
+
+**Frontend domains**: `src/features/<domain>/` → `components/`, `hooks/`, `store/`, `services/`, `utils/`, `types.ts`
+**Backend domains**: `src/graphql/<domain>/` → `types/`, `queries.ts`, `mutations.ts`, `subscriptions.ts`, `loaders.ts` (DataLoader for N+1)
+**Shared infra**: `src/lib/` (clients), `src/app/` (routes, providers)
+
+## Frontend Stack
+
+**Framework**: Next.js App Router (routing, SSR/SSG, Turbopack). `src/app/(app)/dashboard/page.tsx`
+
+**UI**: React + Radix UI primitives (a11y). Prefer Radix for structural/interactive, custom only when Radix lacks. `src/features/<domain>/components/`
+
+**State**: Zustand (global sessions). Avoid Redux. `src/features/<domain>/store/`
+
+**Styling**: PandaCSS (type-safe atomic CSS-in-JS, zero-runtime, <10KB)
+- **Tokens/Themes**: `panda.config.ts` semantics (`colors.primary.500`), `_dark`/CSS vars
+- **Atomic**: Inline JSX (`bg-primary-500 p-4`), `css({ color: 'red' })` merges
+- **Recipes**: `cva` (Button variants), `sva` slots (Card), `jsx: ['Button']` track
+- **Merging**: `cx(recipe(), css({ bg: 'red' }))` overrides
+- **Optimize**: `staticCss: { recipes: '*' }`, purge globs, `panda analyze`, Next.js plugins
+
+**Hooks**: react-use (localStorage, useMeasure, useDebounce, sensors), urql (GraphQL cache, SSR, subscriptions, offline, batching)
+
+**Auth**: Better Auth (passkey-first, 2FA), reCAPTCHA (bot mitigation)
+
+## Backend Stack
+
+GraphQL-first, serverless. `src/graphql/<domain>/`
+
+**Schema/Server**: Pothos (code-first), Yoga. `gql.tada` for all GraphQL docs (never raw templates), `graphql-scalars` for custom scalars
+- Modular `queryField`, typed client hooks via `gql.tada`, colocate operations with components/pages, DataLoader in `loaders.ts` (batch, cache, prevent N+1)
+
+**Auth**: Better Auth (JWT/Redis denylist), rotate tokens
+
+**Request Context**: AsyncLocalStorage with `headers()`/`cookies()` → tiny accessors (`getAuthSession()`, `getLocale()`) instead of passing context objects
+
+**ORM**: Drizzle (queries/migrations). **Never** raw SQL except unavoidable complex cases (use parameterized placeholders). Query builder methods (`eq`, `and`, `or`). Schemas/queries per domain: `src/domains/<domain>/data/`
+- `db.select().from(users).where(eq(users.id, userId))`
+
+**Security**: @simplewebauthn/server, Redis limits
+
+## Data Layer
+
+**DB**: PostgreSQL (Neon/pgBouncer), RLS. Scale: Partition (logs/date)
+
+**Cache/RT**: Upstash Redis (cache/pubsub/streams). TTL (24h), event streams
+
+## Payments
+
+**Billing**: Stripe (Checkout/Portal/Invoices/webhooks idempotent). Wallet credit on session complete, 3x retry
+
+## DevOps
+
+**Local**: Docker Compose (stack), bun, Biome (linting/formatting), Lefthook (Git hooks)
+- **Biome Ignore**: Tests (`__tests__/**`, `*.test.*`), generated (`*.generated.*`, `dist/**`), project-specific (`styled-system`, `*.gql.tada.ts`, `drizzle`, `.next`)
+- **Biome Config**: Recommended + custom flow, ignoreUnknown false
+- **Lefthook**: Pre-commit (Biome, type-check), pre-push (tests). `bun add -D lefthook`, `lefthook install`
+- **Entry**: `bun install && migrate && dev`, Lefthook auto-runs, `biome check .` in CI
+
+**Deploy**: Serverless (Vercel), GraphQL BFF. CI: Actions, 99.9% SLO alerts
+
+## Framework Rules
+
+### GraphQL Standards
+- **IDs**: Use `ID` scalar (not `String`). Base64 for keys.
+- **Enums/Unions**: Enums for fixed (Role), unions for polymorphic (Result = Post | User). Limit depth 3-5.
+
+### GraphQL Document Placement
+Colocate operations in domain services (`src/features/<domain>/services/`), `src/graphql/<domain>/`
+- **Routes/pages**: Import from domain services for tree-shaking
+- **Components**: Queries/mutations in domain services, export typed helpers
+- **Stores**: GraphQL docs in domain services
+- **Fragments**: `src/features/<domain>/services/fragments/` with barrel exports
+- **Tests**: Colocate under `src/features/<domain>/`
+- **Typed modules**: `.gql.ts` stay domain-local, enriched by `graphql-env.d.ts`
+
+### Pothos Best Practices
+- **ID Handling**: `exposeId: false` by default (security), `exposeId: true` only when needed
+- **Subscription Ordering**: `subscribe` before `resolve` for TS inference
+- **Extensions**: `extendType` for modularity, integrate gql.tada for E2E types
+- **Errors**: Custom scalars (graphql-scalars), try-catch with GraphQLError

package/assets/knowledge/guides/ui-ux.md

@@ -0,0 +1,44 @@
+---
+name: UI/UX Guidelines
+description: Modern SPA design patterns, PandaCSS, Radix UI, conversational interfaces
+---
+
+# Modern SPA UI/UX
+
+Apply when designing/updating single-page application interfaces. Keep concise, modular, consistent with conversational products (chat-first SaaS).
+
+## Core Principles
+- Minimalist functionalism: Remove clutter, highlight primary content/controls
+- Balanced readability: Letter-spacing 1.2–1.5, line-height ≥1.5, clear hierarchy
+- Global consistency: Reuse tokens for spacing, color, typography, radii
+- Perceived fluidity: Transitions <200ms, never block input
+
+## Visual System
+- **Color**: Dark backgrounds (#111–#1A1A), optional light mode. One accent for CTAs. WCAG AA contrast ≥4.5:1
+- **Shapes**: 8–12px border radius. Cards with subtle shadows (0 1px 3px rgba(0,0,0,0.1))
+- **Typography**: Sans-serif (Inter, SF Pro). Bold headings, progressively larger. Body 14–16px, 1.5 line-height
+
+## Micro-Interactions
+- Duration: 200–400ms ease-in-out
+- Hover: 1.03× scale or deeper shadow
+- Active: 0.95–0.98× for tactile feedback
+- Page transitions: Fade/slide, prefetch routes (<100ms latency)
+
+## Interaction Patterns
+- **Conversational**: Messages top-to-bottom, timestamp/metadata aligned (chat UIs)
+- **Input**: Pin primary composer at viewport bottom, minimal controls
+- **Feedback**: Visual response on every submit/load/state change (spinners, progress, confirmations)
+- **Expandable**: Collapse long sections, keep critical details visible
+
+## UX Guidelines
+- Persistent nav (top/sidebar), limit to 5–7 items
+- Eliminate distractions: No autoplay, reduce focal points
+- Natural scrolling, lazy loading for long lists/media
+- Reusable primitives (buttons, cards, inputs) with consistent props
+- Mobile-first: Validate 320px, 768px, 1024px breakpoints, identical functionality
+
+## Validation
+- Contrast/readability in dark/light (axe-core, Lighthouse ≥90)
+- Hover/tap feedback within 50ms
+- Responsive layouts on phone/tablet/desktop, adjust spacing/typography for overflow
+- Document UI decisions (tokens, components) for reuse

package/assets/knowledge/stacks/nextjs-app.md

@@ -0,0 +1,165 @@
+---
+name: Next.js Application
+description: Next.js App Router, Server Components, data fetching, routing, deployment
+---
+
+# Next.js Development
+
+## When Next.js vs React SPA
+
+**Next.js**: SEO matters, fast initial load, full-stack in one codebase
+**React SPA**: Dashboard/admin, behind auth, separate backend exists
+
+## App Router vs Pages Router
+
+**App Router (app/)** - Recommended:
+- Server Components by default (less JS)
+- Built-in layouts, loading, error states
+- Better data fetching patterns
+
+**Pages Router (pages/)**: Legacy maintenance only
+
+## Server vs Client Components
+
+### Decision Tree
+```
+Needs interactivity? (onClick, useState, hooks)
+├─ YES → 'use client'
+└─ NO → Server Component (default)
+```
+
+**Server Components (default):**
+- Render on server, direct DB access, zero client JS
+- Can't use hooks/handlers
+
+**Client Components ('use client'):**
+- Hooks, handlers, interactivity, ships JS to browser
+
+### Composition Pattern
+Server components wrap client components. Fetch data in server, pass as props to client.
+
+## Data Fetching
+
+### Cache Options
+```typescript
+// Cached forever (default)
+await fetch('https://api.example.com/data')
+
+// Cache with revalidation
+await fetch('...', { next: { revalidate: 3600 } })
+
+// Never cache
+await fetch('...', { cache: 'no-store' })
+```
+
+### Parallel Fetching
+```typescript
+// BAD - Sequential
+const posts = await getPosts()
+const users = await getUsers()
+
+// GOOD - Parallel
+const [posts, users] = await Promise.all([getPosts(), getUsers()])
+```
+
+## Caching & Revalidation
+
+**Time-based (ISR):**
+```typescript
+export const revalidate = 3600 // Every hour
+```
+
+**On-demand:**
+```typescript
+import { revalidatePath, revalidateTag } from 'next/cache'
+revalidatePath('/posts')
+revalidateTag('posts')
+```
+
+**Dynamic (no cache):**
+```typescript
+export const dynamic = 'force-dynamic'
+```
+
+## Routing
+
+### File Structure
+```
+app/page.tsx              → /
+app/about/page.tsx        → /about
+app/blog/[slug]/page.tsx  → /blog/:slug
+app/(marketing)/features/page.tsx → /features (route group)
+```
+
+### Special Files
+- `layout.tsx`: Shared UI for segment + children
+- `loading.tsx`: Loading UI (Suspense boundary)
+- `error.tsx`: Error UI (must be 'use client')
+
+## Authentication
+
+### Middleware (Route Protection)
+```typescript
+// middleware.ts
+export function middleware(request: Request) {
+  const token = request.cookies.get('token')
+  if (!token) return NextResponse.redirect(new URL('/login', request.url))
+}
+
+export const config = { matcher: '/dashboard/:path*' }
+```
+
+### Server Actions (Form Handling)
+```typescript
+// app/actions.ts
+'use server'
+
+export async function createPost(formData: FormData) {
+  const title = formData.get('title')
+  if (!title) return { error: 'Missing title' }
+
+  const post = await db.posts.create({ data: { title } })
+  revalidatePath('/posts')
+  return { success: true, post }
+}
+
+// In component
+<form action={createPost}>
+  <input name="title" />
+  <button type="submit">Create</button>
+</form>
+```
+
+## Performance
+
+**Image**: Use `<Image>` with `priority` for above-fold, `placeholder="blur"` for UX
+**Font**: `next/font/google` for automatic optimization
+**Code Splitting**: `dynamic(() => import('./Heavy'), { ssr: false })` for client-only heavy components
+
+## Common Pitfalls
+
+❌ **'use client' everywhere** → Only for interactivity
+❌ **Over-fetching** → Fetch once in layout/page, pass as props
+❌ **Not streaming** → Use Suspense boundaries
+❌ **Forgetting revalidation** → Always revalidate after mutations
+
+## Environment Variables
+
+```bash
+DATABASE_URL="..." # Server only
+NEXT_PUBLIC_API_URL="..." # Exposed to browser (must start with NEXT_PUBLIC_)
+```
+
+## Decision Guide
+
+**Server Component:**
+- Fetching data, backend access, large dependencies, non-interactive
+
+**Client Component:**
+- Interactive (clicks, state, hooks), browser APIs, event handlers
+
+**API Route:**
+- Hide API keys, webhooks, complex server logic, third-party integrations
+
+**Server Action:**
+- Form submissions, mutations (CRUD), simple server ops

package/assets/knowledge/stacks/node-api.md

@@ -0,0 +1,220 @@
+---
+name: Node.js API
+description: Express/Fastify, REST/GraphQL, authentication, middleware, error handling
+---
+
+# Backend API Development
+
+## REST Structure
+
+```
+GET    /users              List
+POST   /users              Create
+GET    /users/:id          Get
+PATCH  /users/:id          Update
+DELETE /users/:id          Delete
+GET    /users/:id/posts    Nested
+```
+
+**Status**: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error
+
+**Response format (project standard):**
+```json
+{ "data": {...}, "meta": {...} }
+{ "items": [...], "total": 100, "page": 1, "limit": 20 }
+{ "error": { "code": "VALIDATION_ERROR", "message": "...", "field": "..." } }
+```
+
+## N+1 Problem
+
+```javascript
+// BAD - N+1 queries
+for (user of users) { user.posts = await getPosts(user.id) }
+
+// GOOD - Join
+await db.users.findMany({ include: { posts: true } })
+
+// GOOD - Batch fetch
+const userIds = users.map(u => u.id)
+const posts = await db.posts.findMany({ where: { userId: { in: userIds } } })
+
+// GraphQL: DataLoader
+const loader = new DataLoader(async (ids) => {
+  const items = await db.find({ where: { id: { in: ids } } })
+  return ids.map(id => items.filter(i => i.parentId === id))
+})
+```
+
+## Database
+
+**Connection pooling:**
+```javascript
+const pool = new Pool({ max: 20, idleTimeoutMillis: 30000 })
+```
+
+**Caching pattern:**
+```javascript
+async function getUser(id) {
+  const cached = await redis.get(`user:${id}`)
+  if (cached) return JSON.parse(cached)
+
+  const user = await db.users.findUnique({ where: { id } })
+  await redis.set(`user:${id}`, JSON.stringify(user), 'EX', 3600)
+  return user
+}
+
+// Invalidate on update
+async function updateUser(id, data) {
+  const user = await db.users.update({ where: { id }, data })
+  await redis.del(`user:${id}`)
+  return user
+}
+```
+
+## Authentication
+
+**Session vs Token:**
+- Session: Traditional web apps, need fine-grained control
+- Token (JWT): SPAs, mobile apps, microservices
+
+**JWT middleware (project standard):**
+```javascript
+function requireAuth(req, res, next) {
+  const token = req.headers.authorization?.split(' ')[1]
+  if (!token) return res.status(401).json({ error: { code: 'NO_TOKEN' } })
+
+  try {
+    req.userId = jwt.verify(token, process.env.JWT_SECRET).userId
+    next()
+  } catch {
+    res.status(401).json({ error: { code: 'INVALID_TOKEN' } })
+  }
+}
+```
+
+**Authorization patterns:**
+```javascript
+// Role check
+function requireRole(...roles) {
+  return async (req, res, next) => {
+    const user = await db.users.findUnique({ where: { id: req.userId } })
+    if (!roles.includes(user.role)) {
+      return res.status(403).json({ error: { code: 'FORBIDDEN' } })
+    }
+    next()
+  }
+}
+
+// Ownership check
+function requireOwnership(getter) {
+  return async (req, res, next) => {
+    const resource = await getter(req)
+    if (resource.userId !== req.userId) {
+      return res.status(403).json({ error: { code: 'NOT_OWNER' } })
+    }
+    next()
+  }
+}
+```
+
+## Error Handling
+
+**Project standard:**
+```javascript
+class ApiError extends Error {
+  constructor(statusCode, code, message) {
+    super(message)
+    this.statusCode = statusCode
+    this.code = code
+    this.isOperational = true
+  }
+}
+
+// Error middleware (last!)
+app.use((err, req, res, next) => {
+  if (err.isOperational) {
+    return res.status(err.statusCode).json({
+      error: { code: err.code, message: err.message }
+    })
+  }
+
+  console.error('PROGRAMMER ERROR:', err)
+  res.status(500).json({ error: { code: 'INTERNAL_ERROR' } })
+})
+
+// Usage
+if (!user) throw new ApiError(404, 'NOT_FOUND', 'User not found')
+```
+
+## Performance
+
+**Targets**: DB < 100ms, API < 200ms
+
+**Optimize:**
+- N+1 → Joins / DataLoader
+- Connection pooling
+- Redis caching
+- Job queues (background tasks)
+- Pagination (always LIMIT)
+
+## GraphQL Basics
+
+**When**: Complex relationships, flexible queries
+**vs REST**: Simple CRUD → REST
+
+**DataLoader (required for N+1):**
+```javascript
+const postLoader = new DataLoader(async (userIds) => {
+  const posts = await db.posts.findMany({ where: { userId: { in: userIds } } })
+  return userIds.map(id => posts.filter(p => p.userId === id))
+})
+
+// In resolver
+User: {
+  posts: (user) => postLoader.load(user.id)
+}
+```
+
+## Common Patterns
+
+**Repository:**
+```javascript
+class UserRepo {
+  findById(id) { return db.users.findUnique({ where: { id } }) }
+  save(data) { return db.users.create({ data }) }
+}
+```
+
+**Service:**
+```javascript
+class UserService {
+  async createUser(data) {
+    if (!data.email) throw new Error('Email required')
+    return await this.repo.save(data)
+  }
+}
+```
+
+**Middleware chain:**
+```javascript
+app.use(cors())
+app.use(express.json())
+app.use(rateLimit())
+app.use(auth())
+app.use(errorHandler()) // Last!
+```
+
+## Best Practices
+
+✅ Prepared statements (prevent injection)
+✅ Connection pooling
+✅ Index foreign keys
+✅ Rate limit auth endpoints
+✅ Hash passwords (bcrypt/argon2)
+✅ HTTPS only
+✅ Validate server-side
+
+❌ SQL injection (string concat)
+❌ Plain text passwords
+❌ N+1 queries
+❌ No error handling