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

ntc/templates/react_admin/CLAUDE.md

@@ -0,0 +1,210 @@
+# AI Agent Instructions for NTC-Generated React Admin Dashboard Projects
+
+This document provides specific instructions for AI agents (Claude, GPT, etc.) working with NTC-generated React Admin Dashboard projects.
+
+## 📖 Knowledge Base Reading Order
+
+When first approaching this codebase, AI agents should read the knowledge files in this order:
+
+1. **CLAUDE.md** (this file) - AI agent specific instructions
+2. **.knowledge/knowledge_structure.md** - Project structure and organization
+3. **.knowledge/knowledge_description.md** - Architecture overview and technical stack
+4. **.knowledge/knowledge_design_pattern.md** - Design patterns and coding conventions
+
+## 🤖 AI Agent Guidelines
+
+### Before Making Changes
+
+1. **Read the Knowledge Base**: Always read the knowledge files before making any changes to understand the project structure and conventions.
+
+2. **Understand the NTC Structure**: This project follows the NTC (Nexent Toolkit Console) structure with TypeScript, Vite, React Router v7, TanStack Query, and modern React patterns for admin dashboards.
+
+3. **Check Existing Implementations**: Before adding new features, check if similar implementations already exist in `src/components/`, `src/services/`, or `src/pages/`.
+
+### Code Modification Rules
+
+1. **Use TypeScript Strict Mode**: All code must use TypeScript with strict mode enabled. Avoid `any` types whenever possible.
+
+2. **Follow Component Patterns**:
+   - Functional components with hooks
+   - Use TypeScript interfaces for props
+   - Keep components small and focused
+   - Use proper TypeScript types for all variables and functions
+
+3. **API Integration**:
+   - Use the `base.service.ts` for HTTP operations
+   - Use the `api.service.ts` for typed API endpoints
+   - Use TanStack Query hooks (`useApi`, `useApiMutation`) for data fetching
+   - Handle loading and error states properly
+
+4. **State Management**:
+   - Use React Context API for global state (Auth, Theme, Workspace)
+   - Keep context providers at the root level
+   - Use custom hooks for accessing context
+
+5. **Routing**:
+   - Use React Router v7 for routing
+   - Use protected routes for authenticated pages
+   - Use nested routes for layout components
+
+6. **Environment Variables**:
+   - Use `import.meta.env.VITE_*` for environment variables
+   - All configuration should use environment variables, never hardcode values
+
+7. **Follow Naming Conventions**:
+   - Components: `PascalCase` (e.g., `UserProfile`)
+   - Pages: `PascalCase` with `Page` suffix (e.g., `DashboardPage`)
+   - Functions/Hooks: `camelCase` (e.g., `useUserProfile`)
+   - Files: `PascalCase` for components, `camelCase` for utilities
+   - Constants: `UPPER_SNAKE_CASE`
+
+### Admin Dashboard Specific Patterns
+
+1. **Layout Components**:
+   - `DashboardLayout`: Main layout with sidebar and top navigation
+   - `AuthLayout`: Layout for authentication pages
+   - Use nested routes for layout structure
+
+2. **Authentication**:
+   - Use `AuthContext` for authentication state
+   - Use `ProtectedRoute` for route protection
+   - Implement login/register/logout flows
+
+3. **Data Fetching**:
+   - Use TanStack Query for caching and state management
+   - Use `useApi` hook for GET requests
+   - Use `useApiMutation` hook for POST/PUT/PATCH/DELETE
+   - Implement proper error handling and loading states
+
+### External Service Integration
+
+1. **API Communication**:
+   - Use the configured axios instance in `base.service.ts`
+   - Handle authentication with JWT tokens via interceptors
+   - Implement proper error handling and user feedback
+   - Use loading states for async operations
+
+2. **State Management**:
+   - Use React Context for global state (Auth, Theme, Workspace)
+   - Use TanStack Query for server state
+   - Keep component state local when possible
+
+### Development Workflow
+
+1. **Running the Project**:
+   - Install dependencies: `npm install`
+   - Run development server: `npm run dev`
+   - Build for production: `npm run build`
+   - Preview production build: `npm run preview`
+
+2. **Adding New Components**:
+   - Place in `src/components/` for reusable components
+   - Place in `src/pages/` for page-level components
+   - Place in `src/layouts/` for layout components
+   - Follow the existing component patterns
+   - Include TypeScript interfaces for props
+
+3. **Adding API Services**:
+   - Add typed endpoints to `src/services/api.service.ts`
+   - Use the existing `baseService` with interceptors
+   - Follow the existing service patterns
+   - Include proper TypeScript types
+
+4. **Adding Pages**:
+   - Create page components in `src/pages/`
+   - Add routes to `App.tsx`
+   - Use `ProtectedRoute` for authenticated pages
+   - Update navigation in `Sidebar.tsx`
+
+### Testing
+
+1. **Test Structure**: Each component should have corresponding test files in the same directory or in a `__tests__` directory.
+
+2. **Run Tests**: Use `npm test` to run the test suite (when configured).
+
+### Security Considerations
+
+1. **Never Commit Secrets**: Environment variables should never be committed to the repository.
+
+2. **Use HTTPS in Production**: All API calls should use HTTPS in production.
+
+3. **Validate Inputs**: Always validate user inputs both on client and server side.
+
+4. **Sanitize User Content**: When displaying user-generated content, sanitize to prevent XSS attacks.
+
+5. **Protect Routes**: Use `ProtectedRoute` for authenticated pages.
+
+### When to Ask for Clarification
+
+1. If you're unsure about the NTC structure or conventions
+2. If you need to add a new external service integration
+3. If you're modifying the build configuration (vite.config.ts)
+4. If you're changing the TypeScript configuration
+5. If you're modifying the authentication flow
+6. If you're changing the routing structure
+
+## 🎯 Quick Reference
+
+### Import Patterns
+```typescript
+// API services
+import { baseService } from '@/services/base.service'
+import { apiService } from '@/services/api.service'
+
+// React hooks
+import { useApi, useApiMutation } from '@/hooks/useApi'
+
+// Context
+import { useAuth } from '@/context/AuthContext'
+import { useTheme } from '@/context/ThemeContext'
+import { useWorkspace } from '@/context/WorkspaceContext'
+
+// React Router
+import { useNavigate, useLocation } from 'react-router-dom'
+```
+
+### Common Patterns
+```typescript
+// API call with TanStack Query
+const { data, isLoading, error } = useApi(
+  '/endpoint',
+  { enabled: true }
+)
+
+// Mutation with TanStack Query
+const mutation = useApiMutation(
+  (data) => apiService.postEndpoint(data),
+  {
+    onSuccess: () => {
+      // Handle success
+    },
+    onError: (error) => {
+      // Handle error
+    }
+  }
+)
+
+// Authentication
+const { user, login, logout, isAuthenticated } = useAuth()
+
+// Navigation
+const navigate = useNavigate()
+navigate('/dashboard')
+
+// Environment variable
+const apiUrl = import.meta.env.VITE_API_BASE_URL
+```
+
+## 📝 Additional Resources
+
+- React Documentation: https://react.dev/
+- TypeScript Documentation: https://www.typescriptlang.org/
+- Vite Documentation: https://vitejs.dev/
+- React Router Documentation: https://reactrouter.com/
+- TanStack Query Documentation: https://tanstack.com/query/latest
+- Axios Documentation: https://axios-http.com/
+
+---
+
+**Last Updated**: 2026-05-09
+**Template Version**: React Admin Dashboard with TypeScript, Vite 8, React Router 7, TanStack Query

ntc/templates/react_admin/README.md

@@ -0,0 +1,72 @@
+# {project_name} Admin Dashboard
+
+A React + TypeScript + Vite admin dashboard initialized by `ntc react init`.
+
+## Tech Stack
+
+- React 19
+- TypeScript
+- Vite 8
+- Tailwind CSS 4
+- React Router 7
+- TanStack Query
+- Axios
+- Lucide React
+
+## Getting Started
+
+```bash
+npm install
+npm run dev
+```
+
+## Available Scripts
+
+- `npm run dev` - Runs the app in development mode
+- `npm run build` - Builds the app for production
+- `npm run lint` - Runs ESLint
+- `npm run preview` - Previews the production build
+
+## Project Structure
+
+```
+src/
+├── components/      # Reusable UI components
+├── context/        # React context providers
+├── hooks/          # Custom React hooks
+├── layouts/        # Layout components
+├── pages/          # Page components
+├── services/       # API service layer
+├── App.tsx         # Main app component
+├── main.tsx        # Entry point
+└── index.css       # Global styles
+```
+
+## Features
+
+- Authentication with JWT
+- Protected routes
+- Responsive sidebar navigation
+- Theme switching (light/dark)
+- API integration with TanStack Query
+- Type-safe with TypeScript
+
+## Environment Variables
+
+Copy `.env.example` to `.env` and configure:
+
+```bash
+VITE_API_BASE_URL=http://localhost:8000/v1
+```
+
+## Development
+
+The dashboard is designed to work with a Django REST Framework backend. Ensure your backend API is running and CORS is configured to allow requests from this frontend.
+
+## Building for Production
+
+```bash
+npm run build
+```
+
+The built files will be in the `dist/` directory.

ntc/templates/react_admin/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{project_name} Admin Dashboard</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

ntc/templates/react_admin/knowledge/knowledge_description.md

@@ -0,0 +1,202 @@
+# Architecture Overview - {project_name}
+
+This document provides a comprehensive overview of the architecture and technical stack for this NTC-generated React Admin Dashboard project.
+
+## 🏗️ Architecture Overview
+
+This is a modern React admin dashboard built with TypeScript, Vite, React Router v7, and TanStack Query, designed for API-driven administrative interfaces. The architecture follows a component-based approach with clear separation of concerns.
+
+### Core Architecture Principles
+
+- **Component-First Design**: UI is built using reusable, composable components
+- **Type Safety**: TypeScript provides compile-time type checking
+- **API-Centric**: All data flows through a centralized API service
+- **State Management**: React Context for global state, TanStack Query for server state
+- **Modern Build Tool**: Vite provides fast development and optimized production builds
+
+## 🛠️ Technical Stack
+
+### Frontend Framework
+- **React 19**: Latest React with concurrent features
+- **TypeScript 5.9**: Type-safe JavaScript
+- **Vite 8**: Modern build tool with HMR
+
+### Routing & State
+- **React Router 7**: Client-side routing with nested routes
+- **React Hooks**: State management (useState, useEffect, useContext)
+- **React Context API**: Global state management (Auth, Theme, Workspace)
+- **TanStack Query**: Server state management and caching
+
+### HTTP Client
+- **Axios**: Promise-based HTTP client with interceptors
+- **Base Service**: Centralized HTTP client configuration
+- **API Service**: Typed API endpoints
+
+### Development Tools
+- **ESLint**: Code linting
+- **TypeScript ESLint**: TypeScript-specific linting rules
+- **Path Aliases**: `@` mapped to `src/` directory
+
+## 📊 Data Flow Architecture
+
+### API Communication Flow
+```
+Component → useApi/useApiMutation → apiService → baseService → Axios → Backend API
+                                        ↓
+                                    Interceptors
+                                        ↓
+                                Auth Token Injection
+                                        ↓
+                                    Error Handling
+```
+
+### State Management Flow
+```
+User Interaction → Component State → TanStack Query → API Call → Cache Update → Re-render
+                    ↓
+                Context State → Global State Update → Re-render
+```
+
+## 🔐 Authentication Architecture
+
+### JWT Token Management
+- Tokens stored in localStorage
+- Automatic token injection via axios interceptors
+- Token removal on 401 responses
+- Login/logout through AuthContext
+
+### Auth Context Methods
+- `login(credentials)`: Authenticate and store token
+- `register(data)`: Register new user
+- `logout()`: Remove token and clear auth state
+- `refreshToken()`: Refresh expired tokens
+- `isAuthenticated()`: Check auth status
+
+## 🌐 API Service Architecture
+
+### Base Service Configuration
+- Base URL from environment variable
+- 10-second timeout
+- JSON content-type headers
+- Request/response interceptors
+- Error handling utilities
+
+### API Service Methods
+- Typed endpoints for User and Auth
+- GET, POST, PUT, PATCH, DELETE operations
+- File upload support
+- Error logging
+
+## 📁 Component Architecture
+
+### Component Hierarchy
+```
+App.tsx (Root with Routing)
+├── AuthContext Provider
+├── ThemeContext Provider
+├── WorkspaceContext Provider
+├── QueryClient Provider
+├── AuthLayout
+│   └── LoginPage, RegisterPage
+└── DashboardLayout
+    ├── Sidebar
+    ├── TopNav
+    ├── ProtectedRoute
+    └── [Page Components]
+```
+
+### Layout Patterns
+- **DashboardLayout**: Main layout with sidebar and top navigation
+- **AuthLayout**: Layout for authentication pages
+- **ProtectedRoute**: Route protection wrapper
+- **Nested Routes**: Layout-based routing
+
+## 🎯 Context Architecture
+
+### Auth Context
+- User state
+- Access token
+- Authentication status
+- Login, register, logout functions
+- Token refresh logic
+
+### Theme Context
+- Theme mode (light/dark)
+- Theme toggle function
+
+### Workspace Context
+- Current workspace
+- Workspace selection
+- Workspace-related state
+
+## 🔧 Configuration Architecture
+
+### Environment Variables
+- `VITE_API_BASE_URL`: Backend API base URL
+
+### Build Configuration
+- **Vite Config**: Path aliases, React plugin
+- **TypeScript Config**: Strict mode, path mapping
+- **ESLint Config**: React and TypeScript rules
+
+## 🚀 Build Process
+
+### Development Build
+- Vite dev server with HMR
+- TypeScript compilation on-the-fly
+- Source maps for debugging
+- Port: 5173
+
+### Production Build
+- TypeScript compilation
+- Minification and tree-shaking
+- Code splitting
+- Asset optimization
+- Output: `dist/` directory
+
+## 🎯 Performance Considerations
+
+### Optimization Strategies
+- Code splitting with React.lazy
+- Memoization with React.memo
+- TanStack Query caching
+- Lazy loading of components
+- Image optimization
+
+### Best Practices
+- Avoid unnecessary re-renders
+- Use TanStack Query for server state
+- Implement virtual scrolling for long lists
+- Optimize bundle size
+
+## 🔒 Security Considerations
+
+### Security Measures
+- HTTPS in production
+- Input validation
+- XSS prevention
+- CSRF protection (via backend)
+- Secure token storage
+- Protected routes
+
+### Environment Variable Security
+- Never commit `.env` files
+- Use `.env.example` for documentation
+- Server-side secrets should not be exposed to client
+
+## 📈 Scalability Architecture
+
+### Scalability Features
+- Component reusability
+- Service layer abstraction
+- Modular file structure
+- Easy integration with new features
+- Support for multiple API endpoints
+- TanStack Query for efficient data fetching
+
+### Future Extensibility
+- Easy addition of state management libraries
+- Integration with testing frameworks
+- Support for i18n
+- Analytics integration
+- Additional context providers