suvo
/
ai-wpa
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ai-wpa/CLAUDE.md

463 lines
15 KiB
Markdown
Raw Permalink Blame History

# CLAUDE.md - AI Assistant Context
## Project Overview
SiliconPin is a comprehensive web platform built with Next.js 15 that offers multiple services and tools for modern web development and hosting needs. The application provides:
- **Topic Management System**: Rich content creation and management with user ownership
- **Admin Dashboard**: Comprehensive analytics, user management, and service administration
- **Web Services**: Cloud hosting, VPN, Kubernetes deployment, and developer hiring
- **PWA Capabilities**: Full Progressive Web App with offline functionality
- **Speech Tools**: Text-to-speech and voice recognition utilities
- **Payment System**: Balance management and billing integration
- **Authentication**: JWT-based auth with Redis sessions and OAuth integration
## Technology Stack
### Core Framework
- **Next.js 15** - React framework with App Router
- **TypeScript** - Type safety and better developer experience
- **React 19** - Latest React with concurrent features
### UI & Styling
- **Tailwind CSS 4** - Utility-first CSS framework
- **Custom UI Components** - Reusable React components with Tailwind styling
- **next-themes** - Dark/light theme support
- **Lucide React** - Beautiful, customizable icons
- **BlockNote Editor** - Rich text editor with @blocknote/mantine (v0.25.2)
### Authentication & Sessions
- **JWT** - JSON Web Tokens for authentication
- **bcryptjs** - Password hashing
- **Redis** - Session storage (high performance)
- **express-session** - Session management
- **connect-redis** - Redis session store
### Database & Validation
- **MongoDB** - Document database with Mongoose ODM
- **Mongoose** - MongoDB object modeling
- **Zod** - Schema validation and type inference
- **Topic System** - User-owned content with rich text editing and BlockNote editor
### State Management
- **TanStack Query v5** - Server state management
- **React Context** - Client state management
- **React Hook Form** - Form handling and validation
### Development Tools
- **ESLint** - Code linting with Next.js config
- **Prettier** - Code formatting with Tailwind plugin
- **Husky** - Git hooks for code quality
- **lint-staged** - Run linters on staged files
## Project Structure
```
siliconpin/
├── app/ # Next.js App Router
│ ├── api/ # Comprehensive API routes (auth, admin, topics, services, payments)
│ ├── admin/ # Admin dashboard with analytics and management
│ ├── auth/ # Authentication pages
│ ├── topics/ # Topic management system (main content)
│ ├── tools/ # Speech tools and utilities
│ ├── services/ # Web services (hosting, VPN, K8s)
│ ├── dashboard/ # User dashboard
│ ├── globals.css # Global styles and Tailwind
│ ├── layout.tsx # Root layout with providers
│ └── page.tsx # Home page
├── components/ # React components
│ ├── admin/ # Admin-specific components
│ ├── auth/ # Authentication forms and UI
│ ├── topics/ # Topic/content components
│ ├── tools/ # Tool-specific components
│ ├── BlockNoteEditor/ # Rich text editor component
│ ├── ui/ # Reusable UI library
│ ├── header.tsx # Header with navigation
│ ├── footer.tsx # Footer component
│ └── theme-*.tsx # Theme components
├── contexts/ # React contexts
│ ├── AuthContext.tsx # Authentication state
│ └── QueryProvider.tsx # TanStack Query provider
├── lib/ # Utility libraries
│ ├── auth-middleware.ts # API authentication middleware
│ ├── jwt.ts # JWT utilities
│ ├── mongodb.ts # Database connection
│ ├── redis.ts # Redis connection
│ ├── session.ts # Session configuration
│ └── utils.ts # General utilities
├── models/ # Database models
│ ├── user.ts # User model with auth methods
│ ├── topic.ts # Topic model with user ownership
│ ├── billing.ts # Billing and payment models
│ └── transaction.ts # Transaction tracking
└── hooks/ # Custom React hooks
```
## Key Features
### Authentication System
- JWT-based authentication with refresh tokens
- Secure HTTP-only cookies
- Redis session storage for high performance
- Protected routes and API middleware
- User registration, login, logout, token refresh
- User ownership model for content (blogs, etc.)
### API Routes
- `POST /api/auth/register` - Create new user account
- `POST /api/auth/login` - Sign in user
- `POST /api/auth/logout` - Sign out user
- `POST /api/auth/refresh` - Refresh access token
- `GET /api/auth/me` - Get current user info (protected)
### Security Features
- Secure HTTP-only cookies
- Password hashing with bcrypt
- CSRF protection headers
- Input validation with Zod
- Protected API middleware
- Session management with Redis
### Core Application Features
- **Topic Management** - User-owned content creation with rich text editing
- **Admin Dashboard** - Comprehensive analytics, user management, and service administration
- **Web Services** - Cloud hosting, VPN services, Kubernetes deployment, developer hiring
- **Payment System** - Balance management, billing integration, and transaction tracking
- **Speech Tools** - Text-to-speech and voice recognition utilities
- **PWA Support** - Full Progressive Web App with offline capabilities and installability
## Development Commands
```bash
# Development
yarn dev # Start development server with hot reload
yarn build # Build for production
yarn start # Start production server
# Code quality
yarn lint # Run ESLint with auto-fix
yarn typecheck # Run TypeScript compiler (no output)
yarn prepare # Set up Husky pre-commit hooks
```
## Environment Variables
Required environment variables (create `.env.local`):
```env
# Database
MONGODB_URI=mongodb://localhost:27017/siliconpin
# Redis Session Store
REDIS_URL=redis://localhost:6379
# Authentication Secrets
SESSION_SECRET=your-session-secret-must-be-at-least-32-characters-long
JWT_SECRET=your-jwt-secret-change-in-production
JWT_REFRESH_SECRET=your-jwt-refresh-secret-change-in-production
# MinIO Storage (for topic images and file uploads)
MINIO_ENDPOINT=your-minio-endpoint
MINIO_PORT=9000
MINIO_ACCESS_KEY=your-access-key
MINIO_SECRET_KEY=your-secret-key
MINIO_BUCKET=your-bucket-name
# Optional
NODE_ENV=development
PORT=3006
```
## Common Development Tasks
### Adding New API Routes
1. Create new route file in `app/api/`
2. Use the auth middleware for protected routes:
```typescript
import { authMiddleware } from '@/lib/auth-middleware'
export async function GET(request: Request) {
const user = await authMiddleware(request)
if (!user) {
return Response.json({ error: 'Unauthorized' }, { status: 401 })
}
// Your protected logic here
}
```
### Creating New Components
1. Add component in `components/` directory
2. Use custom UI components from components/ui/ when possible
3. Follow existing patterns for styling and props
4. Create index.ts barrel export for cleaner imports
5. Use dynamic imports for heavy components (e.g., BlockNote)
### Adding New Database Models
1. Create model in `models/` directory
2. Define Mongoose schema with proper types
3. Add Zod validation schema
4. Export both model and validation schema
### Form Handling Pattern
```typescript
import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { z } from 'zod'
const schema = z.object({
// Define your schema
})
export function MyForm() {
const form = useForm({
resolver: zodResolver(schema),
defaultValues: {
// Set defaults
},
})
// Handle form submission
}
```
## AI Assistant Instructions
When working on this codebase:
### DO:
- Use TypeScript for all new code
- Follow existing component patterns
- Use custom UI components from components/ui/ when building UI
- Implement proper error handling
- Add Zod validation for API inputs
- Follow the established folder structure
- Use the existing authentication patterns
- Implement responsive design with Tailwind
- Add proper loading and error states
### DON'T:
- Mix different authentication patterns
- Skip TypeScript types
- Create components without proper props interface
- Forget to handle loading/error states
- Skip validation on API routes
- Use different state management patterns
- Add dependencies without checking existing ones
### Code Style
- Use functional components with hooks
- Prefer composition over inheritance
- Use descriptive variable and function names
- Add JSDoc comments for complex functions
- Follow Prettier formatting rules
- Use consistent import ordering
### Key Pages
- `/auth` - Authentication and user management
- `/dashboard` - User analytics and account overview
- `/topics` - Public topic listing and content browsing
- `/topics/new` - Create new topic (protected)
- `/topics/[slug]` - View individual topic content
- `/admin` - Admin dashboard with comprehensive management
- `/services` - Web services (hosting, VPN, Kubernetes)
- `/tools` - Speech tools and utilities
## 🔥 **CRITICAL: PWA Build vs Development Guidelines**
### **When You Need `yarn build` (Production Build Required):**
- ✅ **Service Worker Changes** - New caching strategies, SW updates
- ✅ **Workbox Configuration** - Changes to `next.config.js` PWA settings
- ✅ **Production PWA Testing** - Final validation before deployment
- ✅ **Performance Optimization** - Testing minified/optimized PWA bundle
### **When `yarn dev` is Sufficient (No Build Needed):**
- ✅ **Manifest Changes** - Icons, name, description, screenshots, theme colors
- ✅ **PWA Validation** - Chrome DevTools Application tab checks
- ✅ **Install Button Testing** - Browser install prompts
- ✅ **Icon Updates** - New icon files or sizes
- ✅ **Most PWA Features** - Installability, offline detection, etc.
### **Quick PWA Development Workflow:**
```bash
# 1. Start development (most PWA features work)
yarn dev
# 2. Make manifest/icon changes
# 3. Refresh browser - changes appear immediately
# 4. Validate in Chrome DevTools → Application → Manifest
# 5. Only build when deploying or testing service worker
yarn build && yarn start
```
**🚨 KEY INSIGHT**: PWA manifest changes hot-reload in development mode, making `yarn build` unnecessary for most PWA validation and testing!
---
## Troubleshooting
### Common Issues
1. **BlockNote Editor SideMenu Error**
- **Solution**: Ensure using `@blocknote/mantine` v0.25.2 (not newer versions)
- Import from `@blocknote/mantine` not `@blocknote/react` for BlockNoteView
- Create index.ts barrel export in BlockNoteEditor folder
- Clear cache: `rm -rf .next node_modules/.cache`
- Clean install: `rm -rf node_modules yarn.lock && yarn install`
2. **MongoDB Connection Issues**
- Ensure MongoDB is running locally or connection string is correct
- Check network connectivity for cloud databases
3. **Redis Connection Issues**
- Verify Redis server is running locally
- Check REDIS_URL format: `redis://localhost:6379`
4. **Authentication Not Working**
- Check JWT secrets are set in environment variables
- Verify cookies are being set correctly
- Check browser developer tools for errors
5. **Build Errors**
- Run `yarn typecheck` to identify TypeScript errors
- Check for unused imports or variables
- Verify all environment variables are set
6. **Development Server Issues**
- Clear Next.js cache: `rm -rf .next`
- Reinstall dependencies: `rm -rf node_modules && yarn install`
## Deployment Notes
- This application is optimized for Vercel deployment
- Environment variables must be set in production
- Ensure MongoDB and Redis instances are accessible from production
- Use secure secrets for JWT and session keys
- Enable HTTPS in production for secure cookies
## Contributing
When extending this application:
1. Maintain the established patterns
2. Add proper TypeScript types
3. Include validation schemas
4. Update documentation as needed
5. Test authentication flows
6. Follow security best practices
---
## Application Status
### ✅ **PRODUCTION READY - COMPREHENSIVE PLATFORM**
SiliconPin has evolved into a complete web platform with the following implemented features:
#### **🔐 Authentication & User Management**
- JWT-based authentication with refresh tokens
- OAuth integration (Google, GitHub)
- Redis session management
- Protected routes and API middleware
- User profile management
#### **📝 Topic Management System**
- Rich text editing with BlockNote editor
- User-owned content creation and management
- Tag system with search and filtering
- Image upload with MinIO integration
- Draft/publish workflows
- SEO optimization with metadata
#### **🛠️ Admin Dashboard**
- Comprehensive analytics and reporting
- User management and moderation
- Billing and transaction tracking
- Service administration
- System settings and configuration
- PDF report generation
#### **🌐 Web Services**
- Cloud hosting deployment and management
- VPN service configuration
- Kubernetes orchestration
- Developer hiring marketplace
- Service monitoring and health checks
#### **🎤 Speech Tools**
- Text-to-speech synthesis with multiple voices
- Voice recognition and transcription
- Web Speech API integration
- Audio processing utilities
#### **💰 Payment & Billing System**
- Balance management and top-up
- Transaction history and tracking
- Service billing and invoicing
- Payment gateway integration
- Refund processing
#### **📱 PWA Implementation**
- Full Progressive Web App capabilities
- Offline functionality with service worker
- App installation and native feel
- Responsive design across devices
- Push notification support
### **🚀 Technical Architecture**
#### **Backend Infrastructure**
- **50+ API Endpoints**: Comprehensive REST API coverage
- **8 Database Models**: User, Topic, Billing, Transaction, etc.
- **MongoDB Integration**: Full CRUD operations with Mongoose
- **Redis Caching**: High-performance session and data caching
- **MinIO Storage**: File and image management
#### **Frontend Excellence**
- **150+ Component Library**: Reusable React components
- **TypeScript**: 100% type safety with strict mode
- **Tailwind CSS**: Modern, responsive design system
- **Next.js 15**: Latest framework with App Router
- **PWA Ready**: Installable with offline capabilities
#### **Development Quality**
- **Code Quality**: ESLint, Prettier, and Husky pre-commit hooks
- **Security**: Input validation, CSRF protection, secure cookies
- **Performance**: Optimized bundle, lazy loading, caching strategies
- **Scalability**: Microservice-ready architecture
- **Documentation**: Comprehensive developer documentation
**Status**: **PRODUCTION DEPLOYMENT READY** with full feature set and enterprise-grade architecture.
Reference in New Issue View Git Blame Copy Permalink