Tech Stack

Toàn bộ stack công nghệ chuẩn của PrimeCommerce, áp dụng cho mọi dự án mới.

Frontend

Next.js 14+

App Router + TypeScript. Framework chính cho web.

Tailwind CSS + shadcn/ui

Styling nhanh, component library sẵn dùng.

Thành phần	Công nghệ	Ghi chú
Framework	Next.js 14+ (App Router)	TypeScript bắt buộc
Styling	Tailwind CSS + shadcn/ui	Không sửa trực tiếp file shadcn/ui
State (client)	Zustand	Store nhẹ, đơn giản
State (server)	TanStack Query	Cache, refetch, optimistic updates
Forms	React Hook Form + Zod	Validation bằng schema
Testing	Vitest + React Testing Library	Unit + component tests
E2E	Playwright	End-to-end tests
Skill guides	`/shadcn-ui`, `/tanstack`, `/web-frameworks`, `/frontend-development`	Stack-specific help

Cấu trúc thư mục Next.js

src/
├── app/                    # App Router pages & layouts
│   ├── (auth)/            # Route groups
│   ├── (dashboard)/
│   └── api/               # API routes (lightweight)
├── components/
│   ├── ui/                # shadcn/ui (KHÔNG sửa trực tiếp)
│   └── [feature]/         # Components theo tính năng
├── lib/
│   ├── api/               # API client, fetchers
│   ├── hooks/             # Custom hooks
│   ├── stores/            # Zustand stores
│   ├── utils/             # Hàm tiện ích
│   └── validations/       # Zod schemas
├── types/                 # TypeScript types dùng chung
└── config/                # Cấu hình ứng dụng

Backend

NestJS

Primary API. TypeScript + module architecture.

FastAPI

AI/ML services. Python + async.

Thành phần	Công nghệ	Ghi chú
Primary API	NestJS + TypeScript	Module-based architecture
AI/ML Services	Python + FastAPI	Cho các dịch vụ AI
Database	PostgreSQL	Database chính
Cache/Queue	Redis	Cache + BullMQ queue
ORM (NestJS)	Prisma	Type-safe queries
ORM (FastAPI)	SQLAlchemy	Python ORM
Auth	JWT + Refresh tokens	NextAuth cho Next.js
Message Queue	BullMQ	Redis-backed
Skill guides	`/backend-development`, `/databases`, `/better-auth`	Backend-specific help

Cấu trúc thư mục NestJS

src/
├── modules/
│   └── [feature]/
│       ├── dto/           # Request/Response DTOs
│       ├── entities/      # Prisma models
│       ├── [feature].controller.ts
│       ├── [feature].service.ts
│       ├── [feature].module.ts
│       └── [feature].spec.ts
├── common/
│   ├── decorators/
│   ├── filters/           # Exception filters
│   ├── guards/            # Auth guards
│   ├── interceptors/
│   └── pipes/
├── config/
├── database/
│   └── migrations/
└── main.ts

Cấu trúc thư mục FastAPI

app/
├── api/v1/routes/         # Route handlers
├── core/
│   ├── config.py          # pydantic-settings
│   ├── security.py
│   └── dependencies.py
├── models/                # SQLAlchemy models
├── schemas/               # Pydantic schemas
├── services/              # Business logic
├── repositories/          # Data access
└── main.py

Mobile

Thành phần	Công nghệ
Framework	Expo (React Native) + TypeScript
Navigation	Expo Router
State	Zustand + TanStack Query
Skill guides	`/mobile-development`	Mobile-specific help

Infrastructure

Thành phần	Công nghệ
CI/CD	GitHub Actions
Container	Docker + Docker Compose
Cloud	Tùy dự án (ghi trong CLAUDE.md riêng)
Monitoring	Tùy dự án

Database Schema

Luôn sử dụng migrations khi thay đổi schema. Không bao giờ sửa trực tiếp database.

# Prisma migrations
npx prisma migrate dev --name add_user_profiles
npx prisma generate

# SQLAlchemy migrations
alembic revision --autogenerate -m "add user profiles"
alembic upgrade head

Monorepo Layout (Khuyên dùng)

project/
├── apps/
│   ├── web/               # Next.js frontend
│   ├── api/               # NestJS backend
│   └── worker/            # Background jobs
├── packages/
│   ├── shared/            # Shared types, utils
│   └── ui/                # Shared UI components
├── infra/                 # Docker, k8s configs
├── docs/                  # Documentation
└── CLAUDE.md              # Project-level instructions

Stack-Specific Skills & Guides

Khi làm việc với từng phần của stack, dùng các skills này để có guidance và best practices:

/shadcn-ui — Component library guide

Prefix: /shadcn-ui, /shadcn-ui --add, /shadcn-ui --customizeGuide cho shadcn/ui: thêm component, customize, best practices.

/shadcn-ui                    # Overview
/shadcn-ui --add button       # Add component
/shadcn-ui --customize theme  # Customize theme

Khi dùng: Thêm component, customize design.

/tanstack — Query + Router guide

Prefix: /tanstack, /tanstack --query, /tanstack --routerTanStack Query (React Query) + Router best practices.

/tanstack                     # Overview
/tanstack --query            # Query guide
/tanstack --router           # Router guide

Khi dùng: Caching, data fetching, routing architecture.

/web-frameworks — Next.js + framework best practices

Prefix: /web-frameworks, /web-frameworks nextjs, /web-frameworks performanceFramework-specific patterns: Next.js App Router, layouts, middleware.

/web-frameworks               # Overview all frameworks
/web-frameworks nextjs        # Next.js specific
/web-frameworks performance   # Performance optimization

Khi dùng: Architecture decisions, pattern selection.

/backend-development — API + service architecture

Prefix: /backend-development, /backend-development nestjs, /backend-development api-designNestJS patterns, API design, module architecture.

/backend-development          # Overview
/backend-development nestjs   # NestJS specific
/backend-development api-design # RESTful design

Khi dùng: Service design, API architecture, module structure.

/frontend-development — UI/UX + component best practices

Prefix: /frontend-development, /frontend-development patterns, /frontend-development a11yComponent design, state management, accessibility patterns.

/frontend-development         # Overview
/frontend-development patterns # Common patterns
/frontend-development a11y    # Accessibility

Khi dùng: Component design, UX patterns, accessibility.

/mobile-development — React Native + Expo

Prefix: /mobile-development, /mobile-development expo, /mobile-development native-modulesExpo + React Native patterns, platform differences.

/mobile-development           # Overview
/mobile-development expo      # Expo-specific
/mobile-development native    # Native modules

Khi dùng: Mobile feature development, platform adaptation.

/databases — PostgreSQL + Prisma guide

Prefix: /databases, /databases postgresql, /databases migrationsDatabase design, migrations, query optimization.

/databases                    # Overview
/databases postgresql         # PostgreSQL specific
/databases migrations         # Migration strategy

Khi dùng: Schema design, performance tuning, migrations.

/better-auth — Authentication + authorization

Prefix: /better-auth, /better-auth setup, /better-auth providersAuth flows, JWT, OAuth provider setup.

/better-auth                  # Overview
/better-auth setup            # Initial setup
/better-auth providers        # OAuth providers

Khi dùng: Auth implementation, provider integration.

/payment-integration — Stripe + payment methods

Prefix: /payment-integration, /payment-integration stripe, /payment-integration webhooksPayment gateway integration, webhook handling.

/payment-integration          # Overview
/payment-integration stripe   # Stripe specific
/payment-integration webhooks # Webhook setup

Khi dùng: Payment flow development, transaction handling.

/shopify — Shopify integration

Prefix: /shopify, /shopify api, /shopify appsShopify API, app development, webhook setup.

/shopify                      # Overview
/shopify api                  # API guide
/shopify apps                 # App development

Khi dùng: Shopify-specific features, app integration.

/threejs — 3D graphics with Three.js

Prefix: /threejs, /threejs scene, /threejs materials3D scene setup, materials, animations in React.

/threejs                      # Overview
/threejs scene                # Scene setup
/threejs materials            # Materials guide

Khi dùng: 3D product visualization, interactive scenes.

/shader — GLSL shaders + graphics programming

Prefix: /shader, /shader glsl, /shader fragmentCustom shaders, fragment/vertex shaders, optimization.

/shader                       # Overview
/shader glsl                  # GLSL guide
/shader fragment              # Fragment shaders

Khi dùng: Advanced visual effects, custom rendering.

/remotion — Video generation in React

Prefix: /remotion, /remotion composition, /remotion renderRemotion for programmatic video, compositions, rendering.

/remotion                     # Overview
/remotion composition         # Composition guide
/remotion render              # Rendering guide

Khi dùng: Dynamic video generation, automation.

/google-adk-python — Google Workspace API

Prefix: /google-adk-python, /google-adk-python sheets, /google-adk-python docsGoogle Sheets, Docs, Drive APIs for Python.

/google-adk-python            # Overview
/google-adk-python sheets     # Sheets API
/google-adk-python docs       # Docs API

Khi dùng: Google Workspace integration, document automation.

​Tech Stack

​Frontend

Next.js 14+

Tailwind CSS + shadcn/ui

​Cấu trúc thư mục Next.js

​Backend

NestJS

FastAPI

​Cấu trúc thư mục NestJS

​Cấu trúc thư mục FastAPI

​Mobile

​Infrastructure

​Database Schema

​Monorepo Layout (Khuyên dùng)

​Stack-Specific Skills & Guides

Tech Stack

Frontend

Cấu trúc thư mục Next.js

Backend

Cấu trúc thư mục NestJS

Cấu trúc thư mục FastAPI

Mobile

Infrastructure

Database Schema

Monorepo Layout (Khuyên dùng)

Stack-Specific Skills & Guides