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

ntc/templates/react_structure/CLAUDE.md

@@ -0,0 +1,176 @@
+# AI Agent Instructions for NTC-Generated React Projects
+
+This document provides specific instructions for AI agents (Claude, GPT, etc.) working with NTC-generated React + TypeScript + Vite 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, and modern React patterns.
+
+3. **Check Existing Implementations**: Before adding new features, check if similar implementations already exist in `src/components/` or `src/services/`.
+
+### 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 `apiService` from `src/services/api.ts` for all API calls
+   - Use `authService` for authentication operations
+   - Handle loading and error states properly
+   - Use async/await for asynchronous operations
+
+4. **Environment Variables**:
+   - Use `import.meta.env.VITE_*` for environment variables
+   - All configuration should use environment variables, never hardcode values
+   - Define types for environment variables in a separate file if needed
+
+5. **Follow Naming Conventions**:
+   - Components: `PascalCase` (e.g., `UserProfile`)
+   - Functions/Hooks: `camelCase` (e.g., `useUserProfile`)
+   - Files: `PascalCase` for components, `camelCase` for utilities
+   - Constants: `UPPER_SNAKE_CASE`
+
+### SEO Best Practices
+
+1. **Meta Tags**: Always include proper meta tags for SEO:
+   - Title, description, keywords
+   - Open Graph tags for social sharing
+   - Twitter Card tags
+   - Canonical URLs
+
+2. **Performance**:
+   - Use React.memo for expensive components
+   - Implement code splitting with React.lazy and Suspense
+   - Optimize images with proper alt text
+   - Use semantic HTML elements
+
+3. **Accessibility**:
+   - Use ARIA labels where needed
+   - Ensure keyboard navigation works
+   - Use proper heading hierarchy
+   - Provide alt text for images
+
+### External Service Integration
+
+1. **API Communication**:
+   - Use the configured axios instance in `apiService`
+   - Handle authentication with JWT tokens via `authService`
+   - Implement proper error handling and user feedback
+   - Use loading states for async operations
+
+2. **State Management**:
+   - Use React hooks for local state
+   - Consider using React Context or a state library for global state
+   - Keep state as close to where it's used as 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
+   - Follow the existing component patterns
+   - Include TypeScript interfaces for props
+
+3. **Adding API Services**:
+   - Add endpoint methods to `src/services/api.ts`
+   - Use the existing `apiClient` with interceptors
+   - Follow the existing service patterns
+   - Include proper TypeScript types
+
+### 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.
+
+### 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
+
+## 🎯 Quick Reference
+
+### Import Patterns
+```typescript
+// API service
+import { apiService, authService } from '@/services/api'
+
+// Constants
+import { API_BASE_URL } from '@/utils/constants'
+
+// React hooks
+import { useState, useEffect } from 'react'
+```
+
+### Common Patterns
+```typescript
+// API call with loading and error states
+const [loading, setLoading] = useState(false)
+const [error, setError] = useState<string | null>(null)
+
+const fetchData = async () => {
+  setLoading(true)
+  setError(null)
+  try {
+    const response = await apiService.get('/endpoint')
+    // Handle response
+  } catch (err) {
+    setError('Failed to fetch data')
+  } finally {
+    setLoading(false)
+  }
+}
+
+// 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/
+- Axios Documentation: https://axios-http.com/
+
+---
+
+**Last Updated**: 2026-05-09
+**Template Version**: React 19 + TypeScript + Vite 8

ntc/templates/react_structure/__init__.py

@@ -0,0 +1 @@
+from .main import init_react_project, init_react_project_in_current_dir

ntc/templates/react_structure/index.css

@@ -0,0 +1,21 @@
+* {
+  box-sizing: border-box;
+}
+
+html {
+  scroll-behavior: smooth;
+}
+
+body {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+    sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+code {
+  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
+    monospace;
+}

ntc/templates/react_structure/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}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

ntc/templates/react_structure/knowledge/knowledge_description.md

@@ -0,0 +1,170 @@
+# Architecture Overview - {project_name}
+
+This document provides a comprehensive overview of the architecture and technical stack for this NTC-generated React + TypeScript + Vite project.
+
+## 🏗️ Architecture Overview
+
+This is a modern React application built with TypeScript and Vite, designed for API-driven single-page applications (SPAs). The architecture follows a component-based approach with a 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
+- **Environment-Based Configuration**: Configuration via environment variables
+- **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
+- **React Hooks**: State management (useState, useEffect, useContext)
+- **Context API**: Global state management when needed
+
+### HTTP Client
+- **Axios**: Promise-based HTTP client with interceptors
+- **Custom API Service**: Centralized API communication layer
+
+### Development Tools
+- **ESLint**: Code linting
+- **TypeScript ESLint**: TypeScript-specific linting rules
+- **Path Aliases**: `@` mapped to `src/` directory
+
+## 📊 Data Flow Architecture
+
+### API Communication Flow
+```
+Component → apiService → apiClient (Axios) → Backend API
+                ↓
+            Interceptors
+                ↓
+        Auth Token Injection
+                ↓
+        Error Handling
+```
+
+### State Management Flow
+```
+User Interaction → Component State → API Call → Update State → 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 authService
+
+### Auth Service Methods
+- `login(credentials)`: Authenticate and store token
+- `logout()`: Remove token and clear auth state
+- `getCurrentUser()`: Fetch current user data
+- `isAuthenticated()`: Check auth status
+
+## 🌐 API Service Architecture
+
+### API Client Configuration
+- Base URL from environment variable
+- 10-second timeout
+- JSON content-type headers
+- Request/response interceptors
+
+### Available Methods
+- `get(url, config)`: GET requests
+- `post(url, data, config)`: POST requests
+- `put(url, data, config)`: PUT requests
+- `patch(url, data, config)`: PATCH requests
+- `delete(url, config)`: DELETE requests
+- `uploadFile(url, formData, onUploadProgress)`: File uploads
+
+## 📁 Component Architecture
+
+### Component Hierarchy
+```
+App.tsx (Root)
+├── Header.tsx (Navigation)
+└── [Page Components]
+    └── [UI Components]
+```
+
+### Component Patterns
+- **Functional Components**: Only functional components with hooks
+- **Props Interfaces**: TypeScript interfaces for component props
+- **Custom Hooks**: Reusable logic extraction into custom hooks
+- **Component Composition**: Building complex UI from simple components
+
+## 🔧 Configuration Architecture
+
+### Environment Variables
+- `VITE_API_BASE_URL`: Backend API base URL
+- `VITE_APP_NAME`: Application name
+
+### 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
+- Lazy loading of components
+- Image optimization
+- Bundle size monitoring
+
+### Best Practices
+- Avoid unnecessary re-renders
+- Use useCallback for event handlers
+- Use useMemo for expensive computations
+- Implement virtual scrolling for long lists
+
+## 🔒 Security Considerations
+
+### Security Measures
+- HTTPS in production
+- Input validation
+- XSS prevention
+- CSRF protection (via backend)
+- Secure token storage
+
+### 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
+
+### Future Extensibility
+- Easy addition of state management (Redux, Zustand)
+- Integration with testing frameworks
+- Support for i18n
+- Analytics integration