ntc-dev-kit 1.0.0__py3-none-any.whl

ntc/templates/react_admin/knowledge/knowledge_design_pattern.md

@@ -0,0 +1,448 @@
+# Design Patterns and Coding Conventions - {project_name}
+
+This document describes the design patterns and coding conventions used in this NTC-generated React Admin Dashboard project.
+
+## 🎨 Component Design Patterns
+
+### Functional Component Pattern
+```typescript
+interface ComponentProps {
+  title: string
+  onAction: () => void
+}
+
+const Component: React.FC<ComponentProps> = ({ title, onAction }) => {
+  // Component logic
+  return <div>{title}</div>
+}
+
+export default Component
+```
+
+### Custom Hook Pattern
+```typescript
+const useCustomHook = (param: string) => {
+  const [state, setState] = useState<string>('')
+
+  useEffect(() => {
+    // Effect logic
+  }, [param])
+
+  return state
+}
+```
+
+### Context Provider Pattern
+```typescript
+interface ContextType {
+  value: string
+  setValue: (value: string) => void
+}
+
+const MyContext = createContext<ContextType | undefined>(undefined)
+
+export const MyProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const [value, setValue] = useState('')
+  
+  return (
+    <MyContext.Provider value={{ value, setValue }}>
+      {children}
+    </MyContext.Provider>
+  )
+}
+
+export const useMyContext = () => {
+  const context = useContext(MyContext)
+  if (!context) {
+    throw new Error('useMyContext must be used within MyProvider')
+  }
+  return context
+}
+```
+
+### Protected Route Pattern
+```typescript
+const ProtectedRoute: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const { isAuthenticated } = useAuth()
+  const navigate = useNavigate()
+
+  useEffect(() => {
+    if (!isAuthenticated) {
+      navigate('/login')
+    }
+  }, [isAuthenticated, navigate])
+
+  if (!isAuthenticated) {
+    return null
+  }
+
+  return <>{children}</>
+}
+```
+
+## 🔧 Service Layer Pattern
+
+### Base Service Pattern
+```typescript
+const baseService = {
+  get: <T>(url: string, config = {}) => axios.get<T>(url, config),
+  post: <T>(url: string, data = {}, config = {}) => axios.post<T>(url, data, config),
+  // ... other methods
+}
+```
+
+### API Service Pattern
+```typescript
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+export const apiService = {
+  getUsers: () => baseService.get<User[]>('/users'),
+  getUser: (id: string) => baseService.get<User>(`/users/${id}`),
+  createUser: (data: Partial<User>) => baseService.post<User>('/users', data),
+  // ... other methods
+}
+```
+
+## 📝 TypeScript Patterns
+
+### Interface for Props
+```typescript
+interface ButtonProps {
+  label: string
+  onClick: () => void
+  disabled?: boolean
+  variant?: 'primary' | 'secondary'
+}
+
+const Button: React.FC<ButtonProps> = ({ label, onClick, disabled = false, variant = 'primary' }) => {
+  return <button onClick={onClick} disabled={disabled}>{label}</button>
+}
+```
+
+### Type Guards
+```typescript
+const isString = (value: unknown): value is string => {
+  return typeof value === 'string'
+}
+
+const processValue = (value: unknown) => {
+  if (isString(value)) {
+    return value.toUpperCase()
+  }
+  return 'DEFAULT'
+}
+```
+
+### Generic Types
+```typescript
+interface ApiResponse<T> {
+  data: T
+  status: number
+  message: string
+}
+
+const fetchData = async <T>(url: string): Promise<ApiResponse<T>> => {
+  const response = await baseService.get<ApiResponse<T>>(url)
+  return response.data
+}
+```
+
+## 🎯 State Management Patterns
+
+### TanStack Query Pattern
+```typescript
+const useData = (id: string) => {
+  return useQuery({
+    queryKey: ['data', id],
+    queryFn: () => apiService.getData(id),
+    enabled: !!id,
+  })
+}
+
+const useMutationData = () => {
+  const queryClient = useQueryClient()
+  
+  return useMutation({
+    mutationFn: (data: DataType) => apiService.createData(data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['data'] })
+    },
+  })
+}
+```
+
+### Context Pattern
+```typescript
+const AuthContext = createContext<AuthContextType | undefined>(undefined)
+
+export const AuthProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const [user, setUser] = useState<User | null>(null)
+  const [token, setToken] = useState<string | null>(null)
+  
+  const login = async (credentials: LoginCredentials) => {
+    const response = await apiService.login(credentials)
+    setToken(response.data.token)
+    setUser(response.data.user)
+  }
+
+  const logout = () => {
+    setToken(null)
+    setUser(null)
+  }
+
+  return (
+    <AuthContext.Provider value={{ user, token, login, logout, isAuthenticated: !!token }}>
+      {children}
+    </AuthContext.Provider>
+  )
+}
+```
+
+## 🔄 Async Pattern with TanStack Query
+
+```typescript
+const Component: React.FC = () => {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['items'],
+    queryFn: () => apiService.getItems(),
+  })
+
+  const mutation = useMutation({
+    mutationFn: (item: Item) => apiService.createItem(item),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['items'] })
+    },
+  })
+
+  if (isLoading) return <LoadingSpinner />
+  if (error) return <ErrorMessage error={error} />
+  
+  return (
+    <div>
+      {data?.map(item => <div key={item.id}>{item.name}</div>)}
+      <button onClick={() => mutation.mutate({ name: 'New Item' })}>
+        Add Item
+      </button>
+    </div>
+  )
+}
+```
+
+## 🎨 Layout Pattern
+
+### Dashboard Layout Pattern
+```typescript
+const DashboardLayout: React.FC = () => {
+  const [sidebarCollapsed, setSidebarCollapsed] = useState(false)
+
+  return (
+    <div className="dashboard-layout">
+      <Sidebar collapsed={sidebarCollapsed} onToggle={() => setSidebarCollapsed(!sidebarCollapsed)} />
+      <div className={`main-content ${sidebarCollapsed ? 'collapsed' : ''}`}>
+        <TopNav />
+        <main>
+          <Outlet />
+        </main>
+      </div>
+    </div>
+  )
+}
+```
+
+### Auth Layout Pattern
+```typescript
+const AuthLayout: React.FC = () => {
+  const { isAuthenticated } = useAuth()
+  const navigate = useNavigate()
+
+  useEffect(() => {
+    if (isAuthenticated) {
+      navigate('/dashboard')
+    }
+  }, [isAuthenticated, navigate])
+
+  return (
+    <div className="auth-layout">
+      <Outlet />
+    </div>
+  )
+}
+```
+
+## 📦 File Organization Patterns
+
+### Feature-Based Structure
+```
+src/
+├── features/
+│   ├── users/
+│   │   ├── components/
+│   │   ├── services/
+│   │   └── types/
+│   └── settings/
+│       ├── components/
+│       ├── services/
+│       └── types/
+├── components/ (shared)
+├── services/ (shared)
+└── utils/ (shared)
+```
+
+### Type-Based Structure (Current)
+```
+src/
+├── components/ (shared UI)
+├── context/ (global state)
+├── layouts/ (layout components)
+├── pages/ (page components)
+├── services/ (API services)
+├── hooks/ (custom hooks)
+└── utils/ (utilities)
+```
+
+## 🔒 Error Handling Patterns
+
+### TanStack Query Error Handling
+```typescript
+const { data, error } = useQuery({
+  queryKey: ['items'],
+  queryFn: () => apiService.getItems(),
+  retry: 3,
+  onError: (error) => {
+    console.error('Failed to fetch items:', error)
+  },
+})
+```
+
+### Service Error Handling
+```typescript
+try {
+  const response = await baseService.get('/endpoint')
+  return response.data
+} catch (error) {
+  console.error('API Error:', error)
+  throw error
+}
+```
+
+## 🚀 Performance Patterns
+
+### TanStack Query Caching
+```typescript
+const { data } = useQuery({
+  queryKey: ['items'],
+  queryFn: () => apiService.getItems(),
+  staleTime: 5 * 60 * 1000, // 5 minutes
+  cacheTime: 10 * 60 * 1000, // 10 minutes
+})
+```
+
+### Memo Pattern
+```typescript
+const ExpensiveComponent: React.FC<{ data: DataType }> = React.memo(({ data }) => {
+  return <div>{data.name}</div>
+})
+```
+
+## 🧐 Routing Patterns
+
+### Nested Routes Pattern
+```typescript
+<Route path="/" element={<DashboardLayout />}>
+  <Route index element={<DashboardPage />} />
+  <Route path="users" element={<UsersPage />} />
+  <Route path="settings" element={<SettingsPage />} />
+</Route>
+
+<Route path="/auth" element={<AuthLayout />}>
+  <Route path="login" element={<LoginPage />} />
+  <Route path="register" element={<RegisterPage />} />
+</Route>
+```
+
+### Protected Routes Pattern
+```typescript
+<Route
+  path="/dashboard"
+  element={
+    <ProtectedRoute>
+      <DashboardPage />
+    </ProtectedRoute>
+  }
+/>
+```
+
+## 📐 Naming Conventions
+
+### Components
+- **File**: `PascalCase.tsx` (e.g., `UserProfile.tsx`)
+- **Component**: `PascalCase` (e.g., `UserProfile`)
+- **Props Interface**: `ComponentProps` (e.g., `UserProfileProps`)
+
+### Pages
+- **File**: `PascalCasePage.tsx` (e.g., `DashboardPage.tsx`)
+- **Component**: `PascalCase` with `Page` suffix (e.g., `DashboardPage`)
+
+### Contexts
+- **File**: `PascalContext.tsx` (e.g., `AuthContext.tsx`)
+- **Context**: `PascalContext` (e.g., `AuthContext`)
+- **Hook**: `usePascal` (e.g., `useAuth`)
+
+### Hooks
+- **File**: `camelCase.ts` (e.g., `useUserProfile.ts`)
+- **Hook**: `camelCase` starting with `use` (e.g., `useUserProfile`)
+
+### Services
+- **File**: `camelCase.service.ts` (e.g., `api.service.ts`)
+- **Service**: `camelCase` (e.g., `apiService`)
+
+### Types
+- **File**: `PascalCase.types.ts` (e.g., `User.types.ts`)
+- **Interface**: `PascalCase` (e.g., `UserProfile`)
+- **Type**: `PascalCase` (e.g., `ApiResponse`)
+
+### Constants
+- **File**: `camelCase.ts` (e.g., `constants.ts`)
+- **Constant**: `UPPER_SNAKE_CASE` (e.g., `API_BASE_URL`)
+
+## 🎯 Best Practices
+
+### Code Organization
+1. Keep components small and focused
+2. Extract reusable logic into custom hooks
+3. Use TypeScript interfaces for all props
+4. Organize imports (external, internal, types)
+5. Use path aliases (`@/`) for internal imports
+
+### Performance
+1. Use TanStack Query for server state caching
+2. Use React.memo for expensive components
+3. Implement code splitting with React.lazy
+4. Optimize images and assets
+5. Avoid unnecessary re-renders
+
+### Accessibility
+1. Use semantic HTML elements
+2. Provide alt text for images
+3. Ensure keyboard navigation
+4. Use ARIA labels where needed
+5. Test with screen readers
+
+### Security
+1. Sanitize user input
+2. Use HTTPS in production
+3. Validate data on client and server
+4. Never expose sensitive data
+5. Use environment variables for secrets
+6. Protect routes with authentication
+
+### TanStack Query Best Practices
+1. Use meaningful query keys
+2. Implement proper error handling
+3. Configure staleTime and cacheTime
+4. Use optimistic updates for mutations
+5. Implement retry logic for failed requests

ntc/templates/react_admin/knowledge/knowledge_structure.md

@@ -0,0 +1,97 @@
+# Project Structure - {project_name}
+
+This document describes the complete project structure and organization for AI assistants to understand how to work with this codebase.
+
+## 📁 Root Directory Structure
+
+```
+{project_name}/
+├── .env.example           # Environment variables example
+├── .gitignore            # Git ignore patterns
+├── .knowledge/           # AI documentation (this directory)
+├── index.html            # HTML entry point
+├── package.json          # Node.js dependencies
+├── tsconfig.json         # TypeScript configuration
+├── tsconfig.app.json     # TypeScript app configuration
+├── tsconfig.node.json    # TypeScript node configuration
+├── vite.config.ts        # Vite build configuration
+├── README.md             # Project documentation
+└── src/                  # Source code
+```
+
+## 🏗️ Source Directory Structure (`src/`)
+
+```
+src/
+├── main.tsx              # Application entry point
+├── App.tsx               # Root component with routing
+├── index.css             # Global styles
+├── components/           # Reusable UI components
+│   ├── ProtectedRoute.tsx   # Route protection wrapper
+│   ├── Sidebar.tsx           # Sidebar navigation
+│   └── TopNav.tsx            # Top navigation bar
+├── context/              # React Context providers
+│   ├── AuthContext.tsx       # Authentication state
+│   ├── ThemeContext.tsx      # Theme state
+│   └── WorkspaceContext.tsx  # Workspace state
+├── layouts/              # Layout components
+│   ├── DashboardLayout.tsx   # Main dashboard layout
+│   └── AuthLayout.tsx        # Authentication layout
+├── pages/                # Page components
+│   ├── auth/                 # Authentication pages
+│   │   ├── LoginPage.tsx
+│   │   └── RegisterPage.tsx
+│   └── DashboardPage.tsx     # Dashboard page
+├── services/             # API and external services
+│   ├── base.service.ts       # Axios base service
+│   └── api.service.ts        # Typed API endpoints
+├── hooks/                # Custom React hooks
+│   └── useApi.ts             # TanStack Query hooks
+└── utils/                # Utility functions
+```
+
+## 🎯 Key Conventions
+
+### File Naming
+- **Components**: `PascalCase` with `.tsx` extension (e.g., `UserProfile.tsx`)
+- **Pages**: `PascalCase` with `Page` suffix (e.g., `DashboardPage.tsx`)
+- **Contexts**: `PascalCase` with `Context` suffix (e.g., `AuthContext.tsx`)
+- **Services**: `camelCase` with `.service.ts` extension (e.g., `api.service.ts`)
+- **Hooks**: `camelCase` with `.ts` extension (e.g., `useApi.ts`)
+- **Types**: `PascalCase` with `.ts` extension (e.g., `UserTypes.ts`)
+
+### Import Patterns
+- **Components**: `import Component from '@/components/Component'`
+- **Services**: `import { apiService } from '@/services/api.service'`
+- **Contexts**: `import { useAuth } from '@/context/AuthContext'`
+- **Hooks**: `import { useApi } from '@/hooks/useApi'`
+- **Utils**: `import { CONSTANT } from '@/utils/constants'`
+
+### TypeScript Patterns
+- **Props Interface**: Always define interfaces for component props
+- **Generic Types**: Use generics when appropriate for reusable components
+- **Strict Mode**: TypeScript strict mode is enabled
+- **No Any**: Avoid using `any` type, use `unknown` or proper types instead
+
+## 🔄 Development Workflow
+
+1. **Install dependencies**: `npm install`
+2. **Run development server**: `npm run dev`
+3. **Build for production**: `npm run build`
+4. **Preview production build**: `npm run preview`
+5. **Run linter**: `npm run lint`
+
+## 📋 Important Notes for AI
+
+- **Always use TypeScript** with proper type definitions
+- **Follow the component structure** when creating new components
+- **Use the apiService** for all API calls
+- **Use TanStack Query** for data fetching and caching
+- **Handle loading and error states** in async operations
+- **Use environment variables** via `import.meta.env.VITE_*`
+- **Path aliases**: Use `@` for `src/` directory imports
+- **Vite**: This project uses Vite as the build tool
+- **Port**: Development server runs on http://localhost:5173
+- **React Router v7**: Uses the latest React Router for routing
+- **Context API**: Use React Context for global state management
+- **Protected Routes**: Use `ProtectedRoute` component for authenticated pages