diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b47ec15 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,485 @@ +# ๐Ÿค– CodeForge AI Agents Architecture + +## Overview + +CodeForge uses a sophisticated AI agent architecture powered by OpenAI's GPT models to provide intelligent code generation, explanation, optimization, and error repair across the entire application. This document describes the agent system's design, components, and integration patterns. + +## Architecture Principles + +### 1. Modular Design +Each AI capability is encapsulated in specialized functions within service modules, allowing for: +- Independent testing and updates +- Clear separation of concerns +- Easy addition of new AI features +- Flexible model selection per use case + +### 2. Context Awareness +All AI prompts include relevant project context: +- Existing models and their relationships +- Component hierarchy and structure +- Theme configuration and variants +- File contents and dependencies +- Error context from related files + +### 3. Format Specification +Prompts specify exact output formats with schemas: +- JSON mode for structured data +- TypeScript interfaces for type safety +- Python with proper indentation +- Validation and sanitization of responses + +### 4. Graceful Degradation +Robust error handling ensures: +- Clear error messages for users +- Fallback to manual editing +- Retry logic for transient failures +- Rate limit awareness and handling + +## Core Service Modules + +### AIService (`/src/lib/ai-service.ts`) + +The central orchestration layer for all AI operations. + +#### Key Functions + +##### `generateCompleteApp(description: string)` +Generates a complete application structure from natural language. + +**Prompt Strategy:** +- Analyzes description for key entities and relationships +- Creates Prisma models with appropriate field types +- Generates React components with Material UI +- Configures theme with harmonious color palette +- Returns structured JSON with all elements + +**Output:** +```typescript +{ + files: ProjectFile[] + models: PrismaModel[] + theme: ThemeConfig +} +``` + +##### `generateModels(description: string)` +Creates Prisma models from descriptions. + +**Prompt Strategy:** +- Identifies entities and their attributes +- Determines field types (String, Int, DateTime, etc.) +- Creates relations (one-to-many, many-to-many) +- Sets appropriate constraints (unique, required, default) + +**Example:** +``` +Input: "A blog with users, posts, and comments" +Output: User model with posts relation, Post model with author and comments, Comment model with post and author +``` + +##### `generateComponent(description: string, existingComponents: ComponentNode[])` +Generates React component structures. + +**Prompt Strategy:** +- Includes existing components to avoid naming conflicts +- Uses Material UI component library +- Creates proper component hierarchy +- Configures props and children appropriately + +**Output:** +```typescript +{ + id: string + type: string (e.g., "Box", "Card", "Button") + props: Record + children: ComponentNode[] + name: string +} +``` + +##### `generateTheme(description: string)` +Creates Material UI themes with color palettes. + +**Prompt Strategy:** +- Applies color theory for harmonious palettes +- Ensures WCAG AA accessibility (4.5:1 contrast) +- Creates both light and dark variants +- Configures typography hierarchy +- Sets spacing and border radius + +**Validation:** +- Color contrast ratios verified +- Color format validation (hex to OKLCH) +- Semantic color naming (primary, secondary, etc.) + +##### `explainCode(code: string, language: string)` +Provides detailed code explanations. + +**Prompt Strategy:** +- Identifies key patterns and structures +- Explains purpose and functionality +- Notes best practices or anti-patterns +- Suggests improvements if applicable + +##### `improveCode(code: string, language: string)` +Optimizes code quality and performance. + +**Prompt Strategy:** +- Applies framework-specific best practices +- Improves readability and maintainability +- Optimizes performance where applicable +- Maintains existing functionality +- Adds TypeScript types if missing + +##### `generatePlaywrightTests(description: string)` +Creates E2E test scenarios. + +**Prompt Strategy:** +- Defines user flows from description +- Creates step-by-step test actions +- Uses appropriate selectors (role, testid, text) +- Adds meaningful assertions +- Handles edge cases and error states + +##### `generateStorybookStories(componentName: string, description: string)` +Generates Storybook stories. + +**Prompt Strategy:** +- Creates multiple story variations +- Configures args based on prop types +- Organizes by meaningful categories +- Shows different states and edge cases + +##### `generateUnitTests(description: string, testType: string)` +Creates comprehensive test suites. + +**Prompt Strategy:** +- Component tests use React Testing Library +- Function tests cover edge cases +- Hook tests use renderHook utility +- Integration tests combine multiple units +- Includes setup, assertions, and teardown + +### ErrorRepairService (`/src/lib/error-repair-service.ts`) + +Specialized service for error detection and automated repair. + +#### Key Functions + +##### `detectErrors(files: ProjectFile[])` +Scans files for various error types. + +**Detection Methods:** +- **Syntax Errors**: Parse errors in code structure +- **Import Errors**: Missing or incorrect imports +- **Type Errors**: TypeScript type mismatches +- **Lint Errors**: ESLint violations and code smells + +**Output:** +```typescript +{ + id: string + fileId: string + type: 'syntax' | 'import' | 'type' | 'lint' + severity: 'error' | 'warning' + message: string + line: number + suggestion: string +} +``` + +##### `repairError(error: Error, fileContent: string, relatedFiles: ProjectFile[])` +AI-powered error repair with context. + +**Prompt Strategy:** +- Includes error message and stack trace +- Provides file content with line numbers +- Adds related file imports as context +- Explains the fix applied +- Preserves code structure and style + +**Context Examples:** +- Import errors: Include package.json for available packages +- Type errors: Include type definition files +- Component errors: Include parent component context + +##### `batchRepairErrors(errors: Error[], files: ProjectFile[])` +Repairs multiple errors efficiently. + +**Strategy:** +- Groups errors by file +- Applies fixes in dependency order +- Validates fixes don't introduce new errors +- Returns repaired files and success status + +### Generators (`/src/lib/generators.ts`) + +Code generation utilities for project export. + +#### Functions + +##### `generateNextJSProject(appName: string, models: PrismaModel[], components: ComponentNode[], theme: ThemeConfig)` +Creates complete Next.js file structure. + +##### `generatePrismaSchema(models: PrismaModel[])` +Converts visual models to Prisma schema syntax. + +##### `generateMUITheme(theme: ThemeConfig)` +Exports Material UI theme configuration. + +##### `generatePlaywrightTests(tests: PlaywrightTest[])` +Converts visual test definitions to Playwright code. + +##### `generateStorybookStories(stories: StorybookStory[])` +Creates Storybook CSF3 story files. + +##### `generateUnitTests(tests: UnitTest[])` +Generates Vitest test files with React Testing Library. + +##### `generateFlaskApp(config: FlaskConfig)` +Creates Flask application with blueprints and routes. + +## Integration Points + +### Component Integration + +Each designer component integrates AI through consistent patterns: + +#### Model Designer +```typescript +const handleGenerateModels = async () => { + const description = prompt('Describe your data models:') + const result = await AIService.generateModels(description) + if (result) { + setModels(current => [...current, ...result]) + } +} +``` + +#### Component Tree Builder +```typescript +const handleGenerateComponent = async () => { + const description = prompt('Describe the component:') + const result = await AIService.generateComponent(description, components) + if (result) { + setComponents(current => [...current, result]) + } +} +``` + +#### Code Editor +```typescript +const handleExplain = async () => { + const explanation = await AIService.explainCode(currentCode, language) + setExplanation(explanation) +} + +const handleImprove = async () => { + const improved = await AIService.improveCode(currentCode, language) + onFileChange(fileId, improved) +} +``` + +#### Error Panel +```typescript +const handleRepair = async (error: Error) => { + const file = files.find(f => f.id === error.fileId) + const relatedFiles = getRelatedFiles(file, files) + const repaired = await ErrorRepairService.repairError( + error, + file.content, + relatedFiles + ) + onFileChange(file.id, repaired.content) +} +``` + +## Prompt Engineering Best Practices + +### 1. Clear Instructions +```typescript +const prompt = `You are a Next.js expert. Generate a Prisma schema based on this description: +${description} + +Return ONLY valid JSON in this format: +{ + "models": [ + { + "name": "ModelName", + "fields": [...] + } + ] +} + +Ensure: +- Use appropriate field types (String, Int, DateTime, Boolean) +- Add relations where entities reference each other +- Mark required fields with isRequired: true +- Add unique constraints where appropriate` +``` + +### 2. Context Inclusion +```typescript +const contextPrompt = `Existing models: +${JSON.stringify(existingModels, null, 2)} + +Existing components: +${JSON.stringify(existingComponents, null, 2)} + +Theme colors: +${JSON.stringify(theme.variants, null, 2)} + +Now generate: ${description}` +``` + +### 3. Output Validation +```typescript +const result = await spark.llm(prompt, 'gpt-4', true) +const parsed = JSON.parse(result) + +// Validate structure +if (!parsed.models || !Array.isArray(parsed.models)) { + throw new Error('Invalid response format') +} + +// Validate fields +parsed.models.forEach(model => { + if (!model.name || !model.fields) { + throw new Error('Missing required model properties') + } +}) +``` + +### 4. Error Recovery +```typescript +try { + const result = await spark.llm(prompt, 'gpt-4', true) + return JSON.parse(result) +} catch (error) { + if (error.message.includes('rate limit')) { + toast.error('AI service rate limited. Please try again in a moment.') + } else if (error.message.includes('invalid JSON')) { + toast.error('AI response was invalid. Please try again.') + } else { + toast.error('AI generation failed. Please try manual editing.') + } + return null +} +``` + +## Performance Optimization + +### Caching +```typescript +const cacheKey = `ai-explanation-${hash(code)}` +const cached = await spark.kv.get(cacheKey) +if (cached) return cached + +const result = await spark.llm(prompt) +await spark.kv.set(cacheKey, result) +return result +``` + +### Debouncing +```typescript +const debouncedExplain = useMemo( + () => debounce(async (code: string) => { + const explanation = await AIService.explainCode(code, 'typescript') + setExplanation(explanation) + }, 1000), + [] +) +``` + +### Streaming Responses +```typescript +// Future enhancement for long-running generations +const handleGenerateWithStreaming = async () => { + const stream = await AIService.streamGeneration(description) + + for await (const chunk of stream) { + appendToOutput(chunk) + } +} +``` + +## Future Enhancements + +### Multi-Model Support +- Claude for code review and analysis +- Gemini for multimodal design tasks +- Specialized models for different languages + +### Fine-Tuned Models +- Custom models trained on Next.js patterns +- Framework-specific optimizations +- Design system adherence + +### Advanced Features +- Conversational interface for iterative development +- Learning from user corrections +- Project-specific context retention +- Collaborative AI sessions +- Code review agents +- Security analysis agents +- Performance optimization agents + +## Testing AI Features + +### Unit Tests +```typescript +describe('AIService', () => { + it('generates valid Prisma models', async () => { + const result = await AIService.generateModels('User with name and email') + expect(result).toBeDefined() + expect(result.models).toHaveLength(1) + expect(result.models[0].name).toBe('User') + expect(result.models[0].fields).toContainEqual( + expect.objectContaining({ name: 'name', type: 'String' }) + ) + }) +}) +``` + +### Integration Tests +```typescript +describe('Error Repair', () => { + it('fixes import errors with context', async () => { + const file = { content: 'import { Button } from "missing-package"' } + const relatedFiles = [{ content: 'package.json content...' }] + + const repaired = await ErrorRepairService.repairError( + error, + file.content, + relatedFiles + ) + + expect(repaired.content).toContain('@mui/material') + }) +}) +``` + +## Monitoring and Analytics + +### Usage Tracking +```typescript +// Track AI feature usage +const trackAIUsage = async (feature: string, success: boolean) => { + await spark.kv.set(`ai-usage-${Date.now()}`, { + feature, + success, + timestamp: new Date().toISOString() + }) +} +``` + +### Quality Metrics +- Generation success rate +- Error repair effectiveness +- User acceptance of AI suggestions +- API response times +- Cost per operation + +--- + +**For more information, see the [main README](./README.md) and [PRD](./PRD.md).** diff --git a/README.md b/README.md index 358beec..1e75a06 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,135 @@ -# โœจ Welcome to Your Spark Template! -You've just launched your brand-new Spark Template Codespace โ€” everythingโ€™s fired up and ready for you to explore, build, and create with Spark! +# ๐Ÿ”จ CodeForge - Low-Code Next.js App Builder -This template is your blank canvas. It comes with a minimal setup to help you get started quickly with Spark development. +![CodeForge](https://img.shields.io/badge/CodeForge-v4.0-blueviolet) +![Next.js](https://img.shields.io/badge/Next.js-14-black) +![React](https://img.shields.io/badge/React-18-blue) +![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue) +![AI Powered](https://img.shields.io/badge/AI-Powered-green) -๐Ÿš€ What's Inside? -- A clean, minimal Spark environment -- Pre-configured for local development -- Ready to scale with your ideas - -๐Ÿง  What Can You Do? +A comprehensive visual low-code platform for generating production-ready Next.js applications with Material UI, Prisma, Flask backends, and comprehensive testing suites. Built with AI-powered code generation at its core. -Right now, this is just a starting point โ€” the perfect place to begin building and testing your Spark applications. +## โœจ Features -๐Ÿงน Just Exploring? -No problem! If you were just checking things out and donโ€™t need to keep this code: +### ๐ŸŽฏ Core Capabilities +- **Monaco Code Editor** - Full-featured IDE with syntax highlighting, autocomplete, and multi-file editing +- **Prisma Schema Designer** - Visual database model builder with relations and field configuration +- **Component Tree Builder** - Hierarchical React component designer with Material UI integration +- **Theme Designer** - Advanced theming with multiple variants (light/dark/custom) and unlimited custom colors +- **Flask Backend Designer** - Python REST API designer with blueprints, endpoints, and CORS configuration +- **Project Settings** - Configure Next.js options, npm packages, scripts, and build settings -- Simply delete your Spark. -- Everything will be cleaned up โ€” no traces left behind. +### ๐Ÿค– AI-Powered Generation +- **Complete App Generation** - Describe your app and get a full project structure +- **Smart Code Improvements** - Optimize code for performance and best practices +- **Model Generation** - Create Prisma schemas from natural language +- **Component Generation** - Build complex React components with proper structure +- **Theme Generation** - Generate beautiful, accessible color palettes +- **Test Generation** - Create comprehensive E2E, unit, and integration tests +- **Code Explanations** - Understand any code snippet with detailed explanations +- **Auto Error Repair** - Detect and fix syntax, type, import, and lint errors automatically -๐Ÿ“„ License For Spark Template Resources +### ๐Ÿงช Testing & Quality +- **Playwright Designer** - Visual E2E test builder with step-by-step configuration +- **Storybook Designer** - Component story builder with args and variations +- **Unit Test Designer** - Comprehensive test suite builder for components, functions, and hooks +- **Error Detection** - Automated scanning for syntax, type, and lint errors +- **Auto Repair System** - AI-powered context-aware error fixing + +## ๐Ÿš€ Getting Started + +### Quick Start +1. Open the **Documentation** tab in the app for comprehensive guides +2. Use **AI Generate** to scaffold a complete application from a description +3. Navigate between tabs to design models, components, themes, and backend APIs +4. Click **Export Project** to download your complete Next.js application + +### Manual Building +1. **Models Tab** - Create your database schema with Prisma models +2. **Components Tab** - Build your UI component hierarchy +3. **Styling Tab** - Design your theme with custom colors and typography +4. **Flask API Tab** - Configure your backend REST API +5. **Settings Tab** - Configure Next.js and npm packages +6. **Code Editor Tab** - Fine-tune generated code directly +7. **Export** - Download your complete, production-ready application + +## ๐Ÿ“‹ Technology Stack + +### Frontend +- Next.js 14 with App Router +- React 18 with TypeScript +- Material UI 5 +- Monaco Editor +- Tailwind CSS +- Framer Motion + +### Backend & Testing +- Flask REST API (Python) +- Prisma ORM +- Playwright (E2E Testing) +- Vitest + React Testing Library +- Storybook for Component Development + +### AI Integration +- OpenAI GPT-4 for code generation +- Context-aware prompt engineering +- Intelligent error detection and repair +- Natural language to code translation + +## ๐Ÿ“š Documentation + +The application includes comprehensive built-in documentation: +- **README** - Complete feature overview and getting started guide +- **Roadmap** - Completed features and planned enhancements +- **Agents Files** - AI service architecture and integration points + +Access documentation by clicking the **Documentation** tab in the application. + +## ๐Ÿ—บ๏ธ Roadmap + +### โœ… Completed (v1.0 - v4.0) +- Monaco code editor integration +- Visual designers for models, components, and themes +- AI-powered generation across all features +- Multi-theme variant support +- Testing suite designers (Playwright, Storybook, Unit Tests) +- Auto error detection and repair +- Flask backend designer +- Project settings and npm management + +### ๐Ÿ”ฎ Planned +- Real-time preview with hot reload +- Database seeding designer +- API client generator +- Visual form builder +- Authentication designer (JWT, OAuth, sessions) +- Docker configuration generator +- GraphQL API designer +- State management designer (Redux, Zustand, Jotai) +- CI/CD pipeline generator +- Component library export +- Design system generator +- Collaboration features + +## ๐ŸŽจ Design Philosophy + +CodeForge combines the power of visual low-code tools with professional IDE capabilities: +- **Empowering** - Control at both visual and code levels +- **Intuitive** - Complex generation made approachable +- **Professional** - Production-ready, best-practice code output + +## ๐Ÿค Contributing + +CodeForge is built on the Spark platform. Contributions, feature requests, and feedback are welcome! + +## ๐Ÿ“„ License The Spark Template files and resources from GitHub are licensed under the terms of the MIT license, Copyright GitHub, Inc. + +## ๐Ÿ”— Resources + +- [Full Documentation](./PRD.md) - Complete product requirements and design decisions +- [Error Repair Guide](./ERROR_REPAIR_GUIDE.md) - Error detection and repair system documentation + +--- + +**Built with โค๏ธ using GitHub Spark** diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..b515039 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,352 @@ +# ๐Ÿ—บ๏ธ CodeForge Product Roadmap + +## Vision + +CodeForge aims to become the most comprehensive low-code platform for full-stack application development, combining visual design tools, direct code editing, and AI-powered generation to accelerate development while maintaining professional code quality. + +## Release History + +### v1.0 - Foundation (Completed) +**Release Date:** Initial Release + +Core low-code platform with essential designers: +- โœ… Monaco Code Editor integration with syntax highlighting +- โœ… Multi-file editing with tabs +- โœ… Prisma Schema Designer with visual model builder +- โœ… Component Tree Builder for React hierarchies +- โœ… File Explorer with add/delete capabilities +- โœ… Project export functionality +- โœ… Auto-save to persistent storage + +### v1.1 - Enhanced Theming (Completed) +**Release Date:** Week 2 + +Advanced theming capabilities: +- โœ… Material UI Theme Designer +- โœ… Color palette customization +- โœ… Typography configuration +- โœ… Spacing and border radius controls +- โœ… Live theme preview + +### v2.0 - AI Integration (Completed) +**Release Date:** Week 3 + +OpenAI-powered generation across all features: +- โœ… Complete application generation from descriptions +- โœ… AI-powered model generation +- โœ… AI-powered component generation +- โœ… Code explanation feature in editor +- โœ… Code improvement suggestions +- โœ… Natural language to code translation + +### v2.1 - Multi-Theme Variants (Completed) +**Release Date:** Week 4 + +Extended theme system: +- โœ… Multiple theme variants (light, dark, custom) +- โœ… Unlimited custom colors beyond standard palette +- โœ… Theme variant switching +- โœ… AI theme generation with accessibility checks +- โœ… WCAG contrast validation + +### v3.0 - Testing Suite (Completed) +**Release Date:** Week 5 + +Comprehensive testing tools: +- โœ… Playwright E2E Test Designer +- โœ… Storybook Story Designer +- โœ… Unit Test Designer (components, functions, hooks, integration) +- โœ… Visual test step configuration +- โœ… AI test generation for all test types +- โœ… Test export with proper file structure + +### v3.1 - Error Detection & Repair (Completed) +**Release Date:** Week 6 + +Automated quality assurance: +- โœ… Syntax error detection +- โœ… Import error detection +- โœ… TypeScript type error detection +- โœ… ESLint violation detection +- โœ… AI-powered error repair +- โœ… Context-aware fixes using related files +- โœ… Batch repair functionality +- โœ… Repair explanations + +### v3.2 - UI Improvements (Completed) +**Release Date:** Week 7 + +Enhanced user experience: +- โœ… Multi-row tab support for many open features +- โœ… Responsive layout improvements +- โœ… Better error state visualization +- โœ… Improved empty states across designers +- โœ… Loading states for AI operations + +### v4.0 - Full-Stack Development (Completed) +**Release Date:** Week 8 + +Backend and configuration tools: +- โœ… Flask Backend Designer with blueprints +- โœ… REST API endpoint configuration +- โœ… CORS and authentication settings +- โœ… Next.js settings designer +- โœ… npm package management +- โœ… Build script configuration +- โœ… Package manager selection (npm/yarn/pnpm) +- โœ… Complete project settings control + +## Upcoming Releases + +### v4.1 - Real-Time Preview (In Planning) +**Estimated:** Q2 2024 + +Live application preview: +- [ ] Embedded iframe preview pane +- [ ] Hot reload on code/config changes +- [ ] Multiple device viewport simulation +- [ ] Browser DevTools integration +- [ ] Console output capture +- [ ] Network request monitoring + +**Technical Challenges:** +- Sandboxed execution environment +- Hot module replacement (HMR) configuration +- State preservation across reloads +- Error boundary implementation + +### v4.2 - Data Management (In Planning) +**Estimated:** Q2 2024 + +Database and API integration: +- [ ] Database seeding designer +- [ ] Sample data generation with AI +- [ ] API client generator from Flask definitions +- [ ] Request/response type generation +- [ ] API testing playground +- [ ] Mock data management + +**Features:** +- Visual seed data builder +- Realistic data generation with AI +- TypeScript API client with fetch/axios +- Automatic type inference from endpoints + +### v4.3 - Form Builder (In Planning) +**Estimated:** Q2-Q3 2024 + +Visual form design: +- [ ] Drag-and-drop form builder +- [ ] Field type library (text, email, select, etc.) +- [ ] Validation rule configuration +- [ ] Conditional field visibility +- [ ] Multi-step form support +- [ ] Form submission handling +- [ ] Integration with Prisma models + +**Technologies:** +- React Hook Form integration +- Zod schema validation +- Material UI form components + +### v5.0 - Authentication & Security (In Planning) +**Estimated:** Q3 2024 + +Complete authentication system: +- [ ] Authentication strategy designer +- [ ] JWT configuration (frontend + backend) +- [ ] OAuth provider integration (Google, GitHub, etc.) +- [ ] Session management +- [ ] Role-based access control (RBAC) +- [ ] Protected route configuration +- [ ] Password reset flows +- [ ] Email verification flows + +**Security Features:** +- HTTPS enforcement +- CSRF protection +- Rate limiting configuration +- Security headers (CORS, CSP, etc.) +- Input sanitization rules + +**Docker & Deployment:** +- [ ] Dockerfile generation +- [ ] docker-compose configuration +- [ ] Environment variable management +- [ ] Production vs development configs +- [ ] Container orchestration templates + +### v5.1 - GraphQL Support (In Planning) +**Estimated:** Q3 2024 + +Alternative to REST APIs: +- [ ] GraphQL schema designer +- [ ] Resolver configuration +- [ ] Query and mutation builder +- [ ] Subscription support +- [ ] Apollo Server integration +- [ ] GraphQL client generation +- [ ] Schema validation and introspection + +**Features:** +- Visual schema builder with types and relations +- Automatic resolver generation from Prisma +- GraphQL Playground integration +- Type-safe client with generated hooks + +### v5.2 - State Management (In Planning) +**Estimated:** Q3-Q4 2024 + +Advanced state patterns: +- [ ] State management strategy selector +- [ ] Redux Toolkit configuration +- [ ] Zustand store designer +- [ ] Jotai atom configuration +- [ ] Global state designer +- [ ] Action/reducer builder +- [ ] Async state management (React Query) +- [ ] State persistence configuration + +**Designer Features:** +- Visual state flow diagrams +- Action dispatching visualization +- State inspection and debugging +- Performance optimization suggestions + +### v5.3 - CI/CD & DevOps (In Planning) +**Estimated:** Q4 2024 + +Automated deployment pipelines: +- [ ] GitHub Actions workflow generator +- [ ] GitLab CI configuration +- [ ] CircleCI pipeline builder +- [ ] Automated testing in CI +- [ ] Build and deployment stages +- [ ] Environment-specific configs +- [ ] Secrets management +- [ ] Deployment notifications + +**Integrations:** +- Vercel deployment +- Netlify deployment +- AWS deployment (ECS, Lambda) +- Docker registry push +- Database migration in CI + +### v6.0 - Component Libraries & Design Systems (In Planning) +**Estimated:** Q4 2024 + +Advanced design tooling: +- [ ] Component library export as npm package +- [ ] Design token management +- [ ] Component documentation generator +- [ ] Design system designer +- [ ] Variant system configuration +- [ ] Accessibility annotations +- [ ] Component playground + +**Features:** +- Automatic package.json for library +- TypeScript declaration generation +- Component prop documentation +- Usage examples generation +- Versioning and changelog + +### v6.1 - Collaboration (In Planning) +**Estimated:** Q1 2025 + +Team development features: +- [ ] Real-time collaborative editing +- [ ] User presence indicators +- [ ] Comment system on code/designs +- [ ] Change history and versioning +- [ ] Branch/fork functionality +- [ ] Merge conflict resolution +- [ ] Team permissions and roles + +**Technical Requirements:** +- WebSocket or WebRTC for real-time sync +- Operational transformation (OT) or CRDT +- User authentication and authorization +- Activity logging and audit trails + +## Future Considerations (v7.0+) + +### Advanced AI Features +- [ ] Conversational development interface +- [ ] AI pair programming mode +- [ ] Learning from user corrections +- [ ] Project-specific AI training +- [ ] Multi-model AI strategy (Claude, Gemini, etc.) +- [ ] AI code review agent +- [ ] Security vulnerability scanning with AI + +### Platform Expansion +- [ ] Vue.js and Svelte support +- [ ] Angular application generation +- [ ] Mobile app generation (React Native) +- [ ] Desktop app generation (Electron) +- [ ] WordPress plugin generation +- [ ] Shopify theme development + +### Advanced Integrations +- [ ] Database provider integration (PostgreSQL, MySQL, MongoDB) +- [ ] Cloud service integration (AWS, Azure, GCP) +- [ ] Third-party API integration designer +- [ ] Webhook configuration +- [ ] Message queue integration (RabbitMQ, Kafka) +- [ ] Caching layer configuration (Redis) + +### Enterprise Features +- [ ] Self-hosted deployment option +- [ ] Single sign-on (SSO) +- [ ] Audit logging +- [ ] Compliance reporting (GDPR, SOC2) +- [ ] Custom AI model hosting +- [ ] Enterprise support and SLAs + +### Community & Ecosystem +- [ ] Template marketplace +- [ ] Component marketplace +- [ ] Plugin system for custom designers +- [ ] Public project sharing +- [ ] Community themes and palettes +- [ ] Tutorial and learning platform + +## Feature Prioritization + +Features are prioritized based on: + +1. **User Impact** - How many users benefit and how significantly +2. **Technical Feasibility** - Development complexity and dependencies +3. **Strategic Value** - Alignment with long-term product vision +4. **Resource Availability** - Team capacity and expertise +5. **Market Demand** - User requests and competitive landscape + +## Feedback & Contributions + +We welcome feedback on the roadmap! If you have feature requests or want to contribute to development: + +1. Open an issue describing the feature request +2. Participate in roadmap discussions +3. Contribute code for planned features +4. Share use cases and requirements + +## Versioning Strategy + +- **Major versions (x.0)** - Significant new capabilities, potential breaking changes +- **Minor versions (x.y)** - New features, backwards compatible +- **Patch versions (x.y.z)** - Bug fixes and small improvements + +## Release Cadence + +- **Major releases:** Quarterly +- **Minor releases:** Monthly +- **Patch releases:** As needed + +--- + +**Last Updated:** Current +**Next Review:** After v4.1 release + +For more details on current features, see the [README](./README.md) and [PRD](./PRD.md). diff --git a/src/App.tsx b/src/App.tsx index f7abc4a..7cb01e0 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -6,7 +6,7 @@ import { Button } from '@/components/ui/button' import { Badge } from '@/components/ui/badge' import { Card } from '@/components/ui/card' import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@/components/ui/resizable' -import { Code, Database, Tree, PaintBrush, Download, Sparkle, Flask, BookOpen, Play, Wrench, Gear, Cube } from '@phosphor-icons/react' +import { Code, Database, Tree, PaintBrush, Download, Sparkle, Flask, BookOpen, Play, Wrench, Gear, Cube, FileText } from '@phosphor-icons/react' import { ProjectFile, PrismaModel, ComponentNode, ThemeConfig, PlaywrightTest, StorybookStory, UnitTest, FlaskConfig, NextJsConfig, NpmSettings } from '@/types/project' import { CodeEditor } from '@/components/CodeEditor' import { ModelDesigner } from '@/components/ModelDesigner' @@ -19,6 +19,7 @@ import { UnitTestDesigner } from '@/components/UnitTestDesigner' import { FlaskDesigner } from '@/components/FlaskDesigner' import { ProjectSettingsDesigner } from '@/components/ProjectSettingsDesigner' import { ErrorPanel } from '@/components/ErrorPanel' +import { DocumentationView } from '@/components/DocumentationView' import { generateNextJSProject, generatePrismaSchema, generateMUITheme, generatePlaywrightTests, generateStorybookStories, generateUnitTests, generateFlaskApp } from '@/lib/generators' import { AIService } from '@/lib/ai-service' import { toast } from 'sonner' @@ -345,6 +346,10 @@ function App() { )} + + + Documentation + @@ -419,6 +424,10 @@ function App() { onFileSelect={setActiveFileId} /> + + + + diff --git a/src/components/DocumentationView.tsx b/src/components/DocumentationView.tsx new file mode 100644 index 0000000..90667b0 --- /dev/null +++ b/src/components/DocumentationView.tsx @@ -0,0 +1,839 @@ +import { useState } from 'react' +import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs' +import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card' +import { ScrollArea } from '@/components/ui/scroll-area' +import { Badge } from '@/components/ui/badge' +import { Separator } from '@/components/ui/separator' +import { + BookOpen, + MapPin, + FileCode, + CheckCircle, + Clock, + Sparkle, + Code, + Database, + Tree, + PaintBrush, + Flask, + Play, + Cube, + Wrench, + Gear, + Package, + Rocket, + Target, + Lightbulb +} from '@phosphor-icons/react' + +export function DocumentationView() { + const [activeTab, setActiveTab] = useState('readme') + + return ( +
+ +
+ + + + README + + + + Roadmap + + + + Agents Files + + +
+ + +
+ +
+
+
+ +
+
+

CodeForge

+

+ Low-Code Next.js App Builder with AI +

+
+
+ + + +
+

Overview

+

+ CodeForge is a comprehensive visual low-code platform for generating production-ready Next.js applications. + It combines the power of visual designers with direct code editing, AI-powered generation, and a complete + full-stack development toolkit. +

+
+ + + + + + Key Features + + + + } + title="Monaco Code Editor" + description="Full-featured code editor with syntax highlighting, autocomplete, and AI-powered improvements" + /> + } + title="Prisma Schema Designer" + description="Visual database model designer with automatic schema generation and AI assistance" + /> + } + title="Component Tree Builder" + description="Hierarchical component structure builder with drag-and-drop and AI generation" + /> + } + title="Theme Designer" + description="Material UI theme customizer with multiple variants, custom colors, and AI theme generation" + /> + } + title="Flask Backend Designer" + description="Visual Python Flask API designer with blueprints, endpoints, and CORS configuration" + /> + } + title="Playwright Test Designer" + description="E2E test builder with step configuration and AI test generation" + /> + } + title="Unit Test Designer" + description="Comprehensive test suite builder for components, functions, hooks, and integration tests" + /> + } + title="Auto Error Repair" + description="Automated error detection and AI-powered code repair system" + /> + } + title="Project Settings" + description="Configure Next.js options, npm packages, scripts, and build settings" + /> + } + title="AI Integration" + description="OpenAI-powered generation across all features for rapid development" + /> + + + +
+

Getting Started

+ + +
+

+ 1 + Create Your First Model +

+

+ Navigate to the Models tab and create your database schema using the visual designer + or describe your data model to the AI. +

+
+
+

+ 2 + Design Your Components +

+

+ Use the Components tab to build your UI hierarchy visually or let the AI generate + component structures based on your requirements. +

+
+
+

+ 3 + Customize Your Theme +

+

+ Head to the Styling tab to create custom color palettes, manage theme variants (light/dark), + and configure typography. +

+
+
+

+ 4 + Build Your Backend +

+

+ Configure your Flask API in the Flask API tab by creating blueprints and endpoints + with full CORS and authentication support. +

+
+
+

+ 5 + Export Your Project +

+

+ Click Export Project to generate all files including Next.js pages, Prisma schemas, + Flask backend, tests, and configuration files ready for deployment. +

+
+ + +
+ +
+

AI-Powered Features

+

+ CodeForge integrates OpenAI across every designer to accelerate development: +

+
+ + + + + + + + +
+
+ +
+

Technology Stack

+
+ + + Frontend + + +
    +
  • + + Next.js 14 with App Router +
    • +
  • + + React 18 with TypeScript +
    • +
  • + + Material UI 5 +
    • +
  • + + Monaco Editor +
    • +
  • + + Tailwind CSS +
    • +
+ + + + + Backend & Tools + + +
    +
  • + + Flask REST API +
    • +
  • + + Prisma ORM +
    • +
  • + + Playwright E2E Testing +
    • +
  • + + Vitest & React Testing Library +
    • +
  • + + Storybook for Components +
    • +
+ + +
+
+ + + + + + Pro Tips + + + +

๐Ÿ’ก Use the AI Generate feature to quickly scaffold entire applications from descriptions

+

๐Ÿ’ก The Error Repair tab automatically scans and fixes common issues - check it before exporting

+

๐Ÿ’ก Create multiple theme variants (light, dark, custom) in the Styling tab for complete theme support

+

๐Ÿ’ก Test your components with Storybook stories before writing full E2E tests

+

๐Ÿ’ก Flask blueprints help organize your API endpoints by feature or resource

+ + +
+ + + +
+

+ + Product Roadmap +

+

+ Features delivered and planned for CodeForge development +

+ + + +
+
+
+ +

Completed Features

+
+
+ + + + + + + + + + + + + +
+
+ +
+
+ +

Planned Features

+
+
+ + + + + + + + + + + + +
+
+
+
+ + + +
+

+ + Agents Files +

+

+ AI agent configuration and service architecture +

+ + + +
+

AI Service Architecture

+

+ CodeForge uses a modular AI service architecture that integrates OpenAI's GPT models across all features. + Each designer has specialized prompts and validation logic to ensure high-quality generated code. +

+ + + + Core AI Services + Primary modules handling AI operations + + + + + + + + + + + AI Integration Points + Features enhanced by AI capabilities + + +
+ + + + + + + + +
+ + + + + + Prompt Engineering + How we optimize AI interactions + + +
+

Context Preservation

+

+ All AI prompts include relevant project context such as existing models, components, + and theme configurations to ensure generated code integrates seamlessly. +

+
+
+

Format Specification

+

+ Prompts specify exact output formats (JSON, TypeScript, Python) with strict schemas + to ensure parseable and valid responses. +

+
+
+

Best Practices Enforcement

+

+ Generated code follows Next.js, React, and Flask best practices through detailed + prompt instructions and post-processing validation. +

+
+
+

Error Handling

+

+ Fallback mechanisms and retry logic ensure graceful degradation when AI services + are unavailable or responses are malformed. +

+
+ + + + + + + + Future AI Enhancements + + + +
    +
  • + + Multi-Model Support: Integration with Claude, Gemini, and other LLMs for specialized tasks +
    • +
  • + + Fine-Tuned Models: Custom models trained on specific frameworks and design patterns +
    • +
  • + + Code Review Agent: Automated code review with security and performance analysis +
    • +
  • + + Conversational Interface: Chat-based project building with natural language commands +
    • +
  • + + Learning System: AI that learns from user corrections and preferences over time +
    • +
+ + +
+
+ +
+ + +
+ ) +} + +function FeatureItem({ icon, title, description }: { icon: React.ReactNode; title: string; description: string }) { + return ( +
+
{icon}
+
+

{title}

+

{description}

+
+
+ ) +} + +function AIFeatureCard({ title, description }: { title: string; description: string }) { + return ( + + +
+ +
+

{title}

+

{description}

+
+
+ + + ) +} + +function RoadmapItem({ status, title, description, version }: { + status: 'completed' | 'planned' + title: string + description: string + version: string +}) { + return ( + + +
+
+
+

{title}

+ + {version} + +
+

{description}

+
+
+ + + ) +} + +function AgentFileItem({ filename, path, description, features }: { + filename: string + path: string + description: string + features: string[] +}) { + return ( +
+
+
+ + {filename} +
+

{path}

+

{description}

+
+
+

Key Features:

+
    + {features.map((feature, idx) => ( +
  • + + {feature} +
    • + ))} +
+
+
+ ) +} + +function IntegrationPoint({ component, capabilities }: { component: string; capabilities: string[] }) { + return ( +
+

+ + {component} +

+
    + {capabilities.map((capability, idx) => ( +
  • + โ€ข + {capability} +
    • + ))} +
+
+ ) +}