| 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.
