Folder Structure

This skill defines the locked app architecture for Next.js/React projects using Vayu UI. It answers "where does this go?" for every file type and enforces one-way data flow so your project stays organized at scale.

npx skills add Rugved1652/vayu-ui/folder-structure

Use this locked app architecture for Next.js App Router or React projects using Vayu UI. Pages stay thin, API work stays centralized, domain UI lives in containers/, reusable app components live in components/, and toolkit primitives live in top-level ui/.

Structure

project-root/
├── app/                       # routes/layouts/metadata/route handlers only
│   ├── (auth)/                # auth shell: login/register
│   ├── (dashboard)/           # main app shell
│   ├── api/                   # Next route handlers, only if needed
│   ├── layout.tsx             # root providers/fonts/metadata
│   ├── page.tsx               # home
│   └── globals.css
├── api/
│   ├── api.ts                 # axios client singleton, interceptors
│   ├── services/              # raw HTTP functions: authService.ts
│   ├── hooks/                 # TanStack Query: useLogin.ts, useUsers.ts
│   └── types/                 # rare API-only local types
├── ws/
│   ├── ws.ts                  # socket.io client singleton
│   ├── services/              # socket emitters/listeners: chatSocketService.ts
│   ├── hooks/                 # React hooks per channel: useChatSocket.ts
│   └── types/                 # WS event/message payload types
├── containers/
│   ├── Modals/
│   ├── Forms/
│   ├── PopOver/
│   ├── Drawer/
│   ├── Card/
│   └── Sections/
├── ui/
│   ├── components/            # Vayu/custom primitives
│   ├── hooks/                 # primitive-only hooks
│   └── utils/                 # primitive-only helpers
├── components/                # reusable app components, not primitives
├── types/
│   ├── api-types/             # shared API contracts
│   └── enums/
├── utils/
│   ├── validations/           # Zod schemas
│   └── columns/               # TanStack Table columns
├── hooks/                     # non-API app hooks
├── lib/                       # axios/query-client/auth adapters
└── public/

Placement

Prefer types/api-types/ over api/types/ when a contract is reused. Add index.ts barrels inside api/services/, api/hooks/, ws/services/, ws/hooks/, and container category folders when multiple files exist.

Data Flow

app/page or layout -> containers/* -> api/hooks/* -> api/services/* -> api/api.ts -> backend
app/page or layout -> containers/* -> ws/hooks/* -> ws/services/* -> ws/ws.ts -> backend
containers/* -> ui/components/* | components/* | utils/validations/* | utils/columns/* | types/*
api/hooks/* -> api/services/*
api/services/* -> types/api-types/*
ws/hooks/* -> ws/services/*
ws/services/* -> ws/types/*
ui/components/* -> ui/hooks/* | ui/utils/*

Keep imports one-way. Lower layers must not import pages, containers, or domain UI.

Naming

Use PascalCase for React components/enums. Use camelCase for services, schemas, columns, utilities, and hooks.

Recipes

• Page: keep page.tsx orchestration-only. Compose containers/sections; do not define full forms, modals, or columns inline.
• Page size: extract sections after about 100 lines or multiple visual blocks. Never let any page.tsx exceed 400 lines; split into containers/Sections/<Page><SectionName>Section.tsx.
• Form: containers/Forms/<Name>Form.tsx + utils/validations/<feature>Schema.ts + types/api-types/* + api/hooks/use<Operation>.ts.
• Users table page: use api/hooks/useUsers.ts, utils/columns/userColumns.ts, and action UI such as containers/PopOver/UserActionsPopover.tsx.
• Modal/drawer/popover: concrete instance in containers/<Category>/; underlying primitive from ui/components/; Vayu UI usage/composition verified with the MCP usage skill.
• API: components and containers call query hooks, not services. Services perform HTTP only; query hooks own query keys, useQuery, and useMutation.
• WebSocket: containers/ → ws/hooks/use<ChannelName> → ws/services/<feature>SocketService.ts → ws/ws.ts. UI imports hooks only; hooks import services only; services import the socket client only.
• Root utils/: app-level validations, columns, and feature helpers. ui/utils/: primitive-only helpers.

Anti-Patterns

• Do not put domain forms, modals, drawers, popovers, cards, or large sections in ui/ or components/.
• Do not put primitives in containers/.
• Do not call fetch or axios directly from page.tsx, containers, forms, or UI primitives.
• Do not put TanStack Query hooks in root hooks/.
• Do not define table columns inside route pages.
• Do not let app/ become a business-component dumping ground.
• Do not let any page.tsx exceed 400 lines.
• Do not put app validations, columns, or feature helpers in ui/utils/.
• Do not duplicate shared API contracts between api/types/ and types/api-types/.
• Do not import upward, such as api/services importing from containers.
• Do not use Socket.io client directly in UI or containers; always go through ws/hooks/.
• Do not put WS hooks in root hooks/.
• Do not duplicate WS types between ws/types/ and types/ws-types/.