Imported from cfardev/ayv-comercial (apps/client/AGENTS.md). Install upstream with npx skills add cfardev/ayv-comercial --skill client. Copyright stays with the author.

Client App — Agent Guide

See root AGENTS.md for monorepo-wide rules.

Stack

SCREAM Architecture

Organize code by feature/module folders. Each module is self-contained:

src/
├── modules/
│   ├── products/
│   │   ├── components/       # Product-specific components
│   │   ├── hooks/            # Product-specific hooks
│   │   ├── stores/           # Zustand store for this module
│   │   ├── types/            # Zod schemas, TypeScript types
│   │   ├── utils/            # Helpers exclusive to this module
│   │   └── index.ts          # Public exports
│   ├── orders/
│   │   └── ...
│   └── users/
│       └── ...
├── shared/
│   ├── components/           # Reusable UI components (shadcn)
│   ├── hooks/                # Shared hooks
│   ├── lib/                  # Utilities (cn, formatDate, etc.)
│   └── types/                # Shared types/schemas
└── routes/                   # Route definitions

Rules

• Co-location: Keep related code together (components with their hooks, types with their schemas)
• Barrel exports: Each module has index.ts for public API
• No flat structures: Never put all components in a single components/ folder — organize by domain
• Zustand stores: One store per module in stores/, named {module}Store.ts
• Zod schemas: Co-located with types in types/ as schema.ts files
• react-hook-form: Use with Zod resolver, schema per form

Tech Usage

Zod

• Define schemas in types/schema.ts per module
• Use for: form validation, API response validation, env validation

react-hook-form

• Controller components wrap shadcn inputs
• Schema from Zod passed to useForm via zodResolver

Zustand

• Global state in stores/
• Use immer middleware for complex updates
• Co-located with module it manages

shadcn/ui

• Add components via CLI: npx shadcn@latest add [component]
• Customize via components.json preset
• Place in shared/components/ui/

Routing

• routes/ holds route definitions
• Use react-router-dom v7 patterns
• Lazy load route modules with React.lazy + Suspense

UI Conventions

• All clickable elements (buttons, links, interactive cards, etc.) must include cursor-pointer utility class
• Do not place large forms inside Dialog. If a form has more than 4 fields, it must be implemented as a dedicated page/route instead of a modal.
• Every table must have a Pagination component with changeable page size.

Async Data Loading

• For async data fetching, prefer Skeleton placeholders over generic "Loading..." text.
• Skeleton layouts should mirror the final UI structure (tables, lists, cards) to reduce visual shift when data resolves.
• Use isPending (from TanStack Query) to show skeleton; isFetching indicates background refetch and may skip skeleton if cached data is already visible.