pos-system/microservices/.agent/skills/react-enterprise-architect/SKILL.md

name, description, compatibility, metadata

name	description	compatibility	metadata
react-enterprise-architect	React/Next.js enterprise architecture patterns cho GoodGo frontend apps. Use for project structure, component organization, data fetching, routing, và App Router patterns.	next>=16, react>=19, typescript>=5	author version Velik Ho 1.0

React Enterprise Architect / Kiến Trúc React Enterprise

When to Use This Skill / Khi Nào Sử Dụng

Use this skill when:

• Creating new frontend apps (web-client, web-admin, web-merchant...)
• Organizing feature modules / Tổ chức feature modules
• Setting up Next.js App Router / Thiết lập Next.js App Router
• Implementing data fetching patterns / Triển khai patterns fetch data
• Designing component hierarchies / Thiết kế cấu trúc component

Core Principles / Nguyên Tắc Cốt Lõi

1. Feature-Based Organization: Group by feature, not by type
2. Server-First: Prefer Server Components, use Client Components sparingly
3. Colocation: Keep related code together
4. Single Responsibility: Each module has one clear purpose
5. Type Safety: TypeScript everywhere

Project Structure / Cấu Trúc Dự Án

apps/web-{app}/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (routes)/           # Route groups
│   │   ├── api/                # API routes
│   │   ├── layout.tsx          # Root layout
│   │   └── page.tsx            # Home page
│   ├── features/               # Feature modules (CORE)
│   │   ├── auth/               # Authentication feature
│   │   ├── chat/               # Chat feature
│   │   ├── dashboard/          # Dashboard feature
│   │   └── shared/             # Shared components & utils
│   │       ├── components/     # Reusable components
│   │       ├── hooks/          # Custom hooks
│   │       ├── lib/            # Utilities
│   │       ├── types/          # Shared types
│   │       └── i18n/           # Internationalization
│   ├── stores/                 # Zustand stores
│   │   └── __tests__/          # Store tests
│   ├── services/               # API service clients
│   ├── providers/              # React context providers
│   ├── styles/                 # Global styles, theme
│   └── stories/                # Storybook stories (docs)
├── e2e/                        # Playwright E2E tests
├── public/                     # Static assets
└── .storybook/                 # Storybook config

Key Patterns / Mẫu Chính

Feature Module Structure

features/chat/
├── components/                 # Feature-specific components
│   ├── ChatInput.tsx
│   ├── ChatMessage.tsx
│   └── ChatSidebar.tsx
├── hooks/                      # Feature-specific hooks
│   └── useChat.ts
├── types/                      # Feature types
│   └── chat.types.ts
├── utils/                      # Feature utilities
│   └── formatMessage.ts
└── index.ts                    # Public exports (barrel file)

Server vs Client Components

// ✅ GOOD: Server Component (default)
// EN: No "use client" directive - renders on server
// VI: Không có "use client" - render trên server
async function ChatHistory({ userId }: { userId: string }) {
  const messages = await fetchMessages(userId); // Server-side fetch
  return <MessageList messages={messages} />;
}

// ✅ GOOD: Client Component (only when needed)
// EN: Add "use client" for interactivity
// VI: Thêm "use client" khi cần tương tác
'use client';

import { useState } from 'react';

function ChatInput() {
  const [message, setMessage] = useState('');
  return <input value={message} onChange={(e) => setMessage(e.target.value)} />;
}

Data Fetching Pattern

// EN: Server Component with async data fetching
// VI: Server Component với async data fetching
async function Dashboard() {
  // Direct fetch in Server Component
  const stats = await fetchStats();
  
  return (
    <div>
      <StatsCards data={stats} />
      {/* Client component for interactive chart */}
      <InteractiveChart initialData={stats} />
    </div>
  );
}

Route Organization (App Router)

app/
├── (auth)/                     # Auth route group (no layout)
│   ├── login/page.tsx
│   └── register/page.tsx
├── (dashboard)/                # Dashboard route group with layout
│   ├── layout.tsx              # Shared dashboard layout
│   ├── page.tsx                # /dashboard
│   └── settings/page.tsx       # /dashboard/settings
├── layout.tsx                  # Root layout (providers, global UI)
├── loading.tsx                 # Global loading state
├── error.tsx                   # Global error boundary
└── not-found.tsx               # 404 page

Barrel Exports (index.ts)

// features/chat/index.ts
// EN: Export only public API, hide internal components
// VI: Chỉ export public API, ẩn internal components

export { ChatContainer } from './components/ChatContainer';
export { useChat } from './hooks/useChat';
export type { Message, ChatState } from './types/chat.types';

// ❌ DON'T export internal components
// export { ChatMessageBubble } from './components/internal/ChatMessageBubble';

Common Mistakes / Lỗi Thường Gặp

1. Using Client Components Unnecessarily

// ❌ BAD: Every component is client
'use client';
function Header() { return <h1>Title</h1>; }

// ✅ GOOD: Server Component (default)
function Header() { return <h1>Title</h1>; }

2. Mixing Feature Concerns

// ❌ BAD: Chat component directly uses auth store
import { useAuthStore } from '@/stores/auth-store';

function ChatInput() {
  const user = useAuthStore(s => s.user); // Cross-feature dependency
}

// ✅ GOOD: Receive user as prop from parent
function ChatInput({ userId }: { userId: string }) {
  // Feature-isolated, receives data via props
}

3. Forgetting Loading/Error States

// ✅ GOOD: Always handle loading and error
// app/chat/loading.tsx
export default function Loading() {
  return <ChatSkeleton />;
}

// app/chat/error.tsx
'use client';
export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return <ErrorMessage error={error} onRetry={reset} />;
}

Quick Reference / Tham Chiếu Nhanh

Concept	Pattern
Folder structure	Feature-based (features/)
Components location	features/{name}/components/
Shared components	features/shared/components/
Stores	stores/{name}-store.ts
API routes	app/api/{resource}/route.ts
Page routes	app/(group)/page.tsx
Layouts	app/layout.tsx, route layout.tsx
Loading states	loading.tsx per route
Error handling	error.tsx per route

Resources / Tài Nguyên

• React State Management - Zustand, TanStack Query patterns
• React UI Components - Component development
• React Testing Patterns - Testing strategies
• Project Rules - GoodGo coding standards
• Next.js App Router Docs