flowwise-frontend

name	flowwise-frontend
description	Conventions for the FlowWise web app (apps/web). Use whenever working on the Next.js frontend — adding routes, components, API calls, types, or styling. Captures the team's rules so generated code matches the existing structure: App Router, Tailwind, shared @repo/types, components in src/components, API only through src/lib/api, and the dev-only role switcher for previewing roles.

FlowWise frontend conventions

FlowWise is an AI multi-agent internal workflow platform. apps/web owns all user interfaces and talks only to apps/server. You are working as the frontend developer; do not touch apps/server or apps/agentic.

Structure

• Routing: App Router only (src/app). Route groups: (auth) for unauthed, (app) for the authed shell. No Pages Router.
• Components: live in src/components. One component per file, named export matching the file. Server Components by default; add "use client" only when you need interactivity/state.
• Types: import shared domain types from @repo/types (Role, User, WorkflowRun, WorkflowTask, AgentDecision, Department, AuditEvent, status unions). Do not redefine these locally.
• API access: only through src/lib/api. Components must never call apps/server (fetch/axios) directly. src/lib/api/index.ts switches between real (client.ts) and mock (mocks.ts) implementations via NEXT_PUBLIC_USE_MOCKS. Mocks return data shaped to @repo/types.
• Role context: src/lib/context/RoleContext.tsx holds the current role. Keep the dev-only RoleSwitcher so any role's view can be previewed without real auth. Don't remove it; gate it behind a dev check, not auth.

Styling

• Tailwind v4 + shadcn/ui (base-ui variant — polymorphism is the render prop, not asChild). Add shadcn components with bunx shadcn@latest add <name>.
• Skeleton phase: minimal layout only, no real styling until the designer delivers. Placeholder pages render their name in an <h1> + a TODO comment.

Quality bar (impeccable)

• bun run typecheck && bun run lint && bun run test && bun run build must pass.
• tsconfig is strict (incl. noUncheckedIndexedAccess, no unused). Respect it.
• Pre-commit runs lint-staged (prettier + eslint --fix) scoped to apps/web.

Companion skills (installed in this folder)

• frontend-design, web-design-guidelines — visual polish & UX best practices.
• react-best-practices — React 19 composition/perf patterns.
• shadcn — component-library guidance.
• next-dev-loop — verify changes in a running next dev (runtime, not just types).
• tdd — test-driven workflow (pairs with Vitest + Playwright).
• extract-design-system — turn the designer's deliverables into tokens/components.