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

ntc/templates/nextjs/CLAUDE.md

@@ -0,0 +1,181 @@
+# AI Agent Instructions for NTC-Generated Next.js Projects
+
+This document provides specific instructions for AI agents (Claude, GPT, etc.) working with NTC-generated Next.js 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, Next.js App Router, 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 `process.env.NEXT_PUBLIC_*` for environment variables
+   - All configuration should use environment variables, never hardcode values
+
+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. **Metadata API**: Always include proper metadata for SEO:
+   - Use Next.js Metadata API in layout.tsx and page.tsx
+   - Title, description, keywords
+   - Open Graph tags for social sharing
+   - Twitter Card tags
+   - Canonical URLs
+
+2. **Performance**:
+   - Use Next.js Image component for images
+   - Implement code splitting with dynamic imports
+   - Optimize fonts with next/font
+   - Use Server Components when possible
+
+3. **Accessibility**:
+   - Use semantic HTML elements
+   - Provide alt text for images
+   - Ensure keyboard navigation
+   - Use ARIA labels where needed
+   - Follow WCAG guidelines
+
+4. **Structured Data**:
+   - Add JSON-LD structured data for rich snippets
+   - Use Schema.org vocabulary
+   - Include organization, website, and article schemas
+
+### 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 start`
+
+2. **Adding New Components**:
+   - Place in `src/components/` for reusable components
+   - Place in `src/app/` 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 (next.config.js)
+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 = process.env.NEXT_PUBLIC_API_BASE_URL
+```
+
+## 📝 Additional Resources
+
+- Next.js Documentation: https://nextjs.org/docs
+- React Documentation: https://react.dev/
+- TypeScript Documentation: https://www.typescriptlang.org/
+- Axios Documentation: https://axios-http.com/
+
+---
+
+**Last Updated**: 2026-05-09
+**Template Version**: Next.js 15 + React 19 + TypeScript

ntc/templates/nextjs/README.md

@@ -0,0 +1,94 @@
+# {project_name}
+
+A modern Next.js website with SEO best practices, initialized by `ntc init`.
+
+## Tech Stack
+
+- Next.js 15
+- React 19
+- TypeScript
+- Tailwind CSS (optional, can be added)
+- Axios for API communication
+
+## Getting Started
+
+```bash
+npm install
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+## Available Scripts
+
+- `npm run dev` - Starts the development server
+- `npm run build` - Creates an optimized production build
+- `npm start` - Starts the production server
+- `npm run lint` - Runs ESLint
+
+## SEO Features
+
+This template includes comprehensive SEO optimizations:
+
+- **Metadata API**: Next.js Metadata API for dynamic meta tags
+- **Open Graph**: Social media sharing optimization
+- **Twitter Cards**: Twitter card support
+- **Robots.txt**: Search engine crawling configuration
+- **Sitemap**: Sitemap generation (can be added)
+- **Canonical URLs**: Prevent duplicate content issues
+- **Structured Data**: Schema.org support (can be added)
+
+## Environment Variables
+
+Copy `.env.example` to `.env.local` and configure:
+
+```env
+NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
+NEXT_PUBLIC_SITE_NAME={project_name}
+NEXT_PUBLIC_SITE_URL=http://localhost:3000
+NEXT_PUBLIC_SITE_DESCRIPTION=A modern website built with Next.js
+NEXT_PUBLIC_SITE_KEYWORDS=nextjs,react,typescript
+```
+
+## Project Structure
+
+```
+src/
+├── app/
+│   ├── layout.tsx       # Root layout with SEO metadata
+│   ├── page.tsx         # Home page
+│   └── globals.css      # Global styles
+├── components/          # Reusable components
+├── services/            # API services
+└── utils/              # Utility functions
+```
+
+## SEO Best Practices
+
+1. **Meta Tags**: Each page should have appropriate meta tags
+2. **Semantic HTML**: Use proper HTML5 semantic elements
+3. **Performance**: Optimize images and use code splitting
+4. **Accessibility**: Ensure proper ARIA labels and keyboard navigation
+5. **Mobile-First**: Responsive design for all screen sizes
+
+## Deployment
+
+### Vercel
+
+```bash
+npm install -g vercel
+vercel
+```
+
+### Docker
+
+```bash
+docker build -t {project_name} .
+docker run -p 3000:3000 {project_name}
+```
+
+## Learn More
+
+- [Next.js Documentation](https://nextjs.org/docs)
+- [React Documentation](https://react.dev)
+- [TypeScript Documentation](https://www.typescriptlang.org)

ntc/templates/nextjs/knowledge/knowledge_description.md

@@ -0,0 +1,208 @@
+# Architecture Overview - {project_name}
+
+This document provides a comprehensive overview of the architecture and technical stack for this NTC-generated Next.js project.
+
+## 🏗️ Architecture Overview
+
+This is a modern Next.js website built with TypeScript, Next.js App Router, and React Server Components, designed for SEO-optimized websites with excellent performance.
+
+### Core Architecture Principles
+
+- **Server-First Design**: Leverage Next.js Server Components for better performance and SEO
+- **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
+- **SEO-Optimized**: Built-in SEO best practices with Next.js Metadata API
+
+## 🛠️ Technical Stack
+
+### Frontend Framework
+- **Next.js 15**: Latest Next.js with App Router
+- **React 19**: Latest React with Server Components
+- **TypeScript 5.9**: Type-safe JavaScript
+
+### Routing & State
+- **Next.js App Router**: File-based routing with nested layouts
+- **React Server Components**: Server-side rendering by default
+- **React Client Components**: Client-side interactivity when needed
+- **React Hooks**: State management for Client Components
+
+### HTTP Client
+- **Axios**: Promise-based HTTP client with interceptors
+- **Custom API Service**: Centralized API communication layer
+
+### Development Tools
+- **ESLint**: Code linting with Next.js configuration
+- **TypeScript**: Type checking
+- **Path Aliases**: `@` mapped to `src/` directory
+
+## 📊 Data Flow Architecture
+
+### API Communication Flow
+```
+Server Component → API Service → apiClient (Axios) → Backend API
+                    ↓
+                Interceptors
+                    ↓
+            Auth Token Injection
+                    ↓
+            Error Handling
+```
+
+### Rendering Flow
+```
+Request → Server Component → Data Fetching → HTML Generation → Client Hydration
+```
+
+## 🔐 Authentication Architecture
+
+### JWT Token Management
+- Tokens stored in localStorage (Client Components)
+- 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
+- Error handling utilities
+
+### 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
+
+## 📁 Component Architecture
+
+### Component Hierarchy
+```
+layout.tsx (Root Layout)
+├── Header.tsx (Navigation)
+└── page.tsx (Home Page)
+    └── [Child Components]
+```
+
+### Component Patterns
+- **Server Components**: Default for better performance and SEO
+- **Client Components**: For interactivity (add 'use client' directive)
+- **Layout Components**: Shared UI across routes
+- **Page Components**: Route-specific content
+
+## 🔧 Configuration Architecture
+
+### Environment Variables
+- `NEXT_PUBLIC_API_BASE_URL`: Backend API base URL
+- `NEXT_PUBLIC_SITE_NAME`: Website name
+- `NEXT_PUBLIC_SITE_URL`: Website URL
+- `NEXT_PUBLIC_SITE_DESCRIPTION`: SEO description
+- `NEXT_PUBLIC_SITE_KEYWORDS`: SEO keywords
+
+### Build Configuration
+- **Next.js Config**: Security headers, image domains
+- **TypeScript Config**: Strict mode, path mapping
+- **ESLint Config**: Next.js and TypeScript rules
+
+## 🚀 Build Process
+
+### Development Build
+- Next.js dev server with HMR
+- TypeScript compilation on-the-fly
+- Source maps for debugging
+- Port: 3000
+
+### Production Build
+- TypeScript compilation
+- Server-side rendering
+- Static generation where possible
+- Code splitting
+- Asset optimization
+- Output: `.next/` directory
+
+## 🎯 Performance Considerations
+
+### Optimization Strategies
+- Server Components by default
+- Code splitting with dynamic imports
+- Image optimization with Next.js Image component
+- Font optimization with next/font
+- Automatic CSS optimization
+- Tree shaking
+
+### Best Practices
+- Use Server Components when possible
+- Use Client Components only for interactivity
+- Implement proper caching strategies
+- Optimize images and assets
+- Use streaming for large pages
+
+## 🔒 Security Considerations
+
+### Security Measures
+- HTTPS in production
+- Security headers configured
+- 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
+
+## 📈 SEO Architecture
+
+### SEO Features
+- **Metadata API**: Dynamic meta tags per page
+- **Open Graph**: Social media sharing optimization
+- **Twitter Cards**: Twitter card support
+- **Canonical URLs**: Prevent duplicate content
+- **Structured Data**: JSON-LD for rich snippets
+- **Sitemap**: Automatic sitemap generation
+- **Robots.txt**: Search engine crawling configuration
+
+### SEO Best Practices
+- Semantic HTML elements
+- Proper heading hierarchy
+- Alt text for images
+- Meta descriptions
+- Mobile-responsive design
+- Fast page load times
+
+## 🔒 Accessibility Architecture
+
+### Accessibility Features
+- Semantic HTML
+- ARIA labels where needed
+- Keyboard navigation
+- Screen reader support
+- Color contrast compliance
+- Focus management
+
+## 📈 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 libraries
+- Integration with testing frameworks
+- Support for i18n
+- Analytics integration
+- Additional SEO features