An AI-powered full-stack development platform that transforms natural language into production-ready web applications

codeforge-demo.mp4

---

Table of Contents

• Overview
• Features
• Tech Stack
• Architecture
• Installation
• Configuration
• Usage
• API Reference
• Project Structure
• Development
• Deployment
• Troubleshooting
• Contributing
• License

---

Overview

CodeForge is a sophisticated AI-powered development platform that enables developers to generate complete, production-ready web applications through natural language prompts ( its like a Bolt clone ). Leveraging state-of-the-art language models (GPT-4o and Claude Sonnet 4), CodeForge intelligently creates React/Next.js applications with proper component architecture, styling, and functionality.

What Makes CodeForge Different?

• Production-Ready Code: Generates complete applications using shadcn/ui components and Tailwind CSS
• Real-Time Preview: Instant visual feedback with live code execution in isolated sandboxes
• Multi-Model Support: Choose between OpenAI GPT-4o and Anthropic Claude Sonnet 4
• Conversational Development: Iterative refinement through natural conversation
• Smart Architecture: Intelligent file structuring, component composition, and dependency management
• E2B Sandbox Integration: Safe, isolated code execution environment with full Node.js support

E2B sandboxes example :

---

Features

Core Capabilities

• Instant App Generation: Transform ideas into complete web applications in seconds
• Natural Language Interface: Describe what you want in plain English
• Framework-Aware: Understands Next.js, React, and modern web development patterns
• Beautiful UI by Default: Automatically integrates shadcn/ui components with polished designs
• Responsive Design: Mobile-first, accessible interfaces out of the box
• Live Code Editing: Real-time code preview and execution
• Session Management: Persistent conversations with context retention
• Interactive Terminal: Execute shell commands within the sandbox environment

Developer Experience

• Automatic Dependency Management: Smart package.json generation with required dependencies
• Intelligent Code Parsing: Extracts and organizes generated artifacts
• Multi-Provider Support: Switch between GPT-4o and Claude Sonnet 4 on the fly
• Streaming Responses: Real-time AI response streaming for better UX
• Error Handling: Comprehensive error boundaries and graceful degradation
• Hot Reload: Instant feedback during development

---

Tech Stack

Frontend

Technology	Version	Purpose
Next.js	16.0.3	React framework with App Router
React	19.2.0	UI library
TypeScript	5.x	Type safety
Tailwind CSS	4.x	Utility-first styling
shadcn/ui	Latest	High-quality component library
Radix UI	Latest	Accessible primitives
Lucide React	0.553.0	Icon library
React Markdown	10.1.0	Markdown rendering
React Syntax Highlighter	16.1.0	Code syntax highlighting

Backend

Technology	Version	Purpose
FastAPI	0.100+	Modern Python web framework
Python	3.9+	Runtime environment
OpenAI API	Latest	GPT-4o language model
Anthropic API	Latest	Claude Sonnet 4 language model
E2B	Latest	Code execution sandboxes
Pydantic	Latest	Data validation
python-dotenv	Latest	Environment management

---

Architecture

CodeForge follows a modern, scalable architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────────┐
│                        User Interface                       │
│                    (Next.js + React)                        │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                    Frontend Application                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ Chat Panel   │  │Preview Panel │  │  Terminal    │       │
│  │  Component   │  │  Component   │  │  Component   │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└────────────────────┬────────────────────────────────────────┘
                     │ HTTP/WebSocket
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                    FastAPI Backend                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   API        │  │   Prompts    │  │  Services    │       │
│  │  Endpoints   │  │   Engine     │  │   Layer      │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└────┬────────────────────┬────────────────────┬──────────────┘
     │                    │                    │
     ▼                    ▼                    ▼
┌─────────┐         ┌─────────┐         ┌──────────┐
│ OpenAI  │         │Anthropic│         │   E2B    │
│   API   │         │   API   │         │ Sandbox  │
└─────────┘         └─────────┘         └──────────┘

Key Components

1. Frontend (Next.js)

   • Chat Panel: User interaction, prompt input, model selection
   • Preview Panel: Live iframe preview of generated applications
   • Terminal: Interactive shell for sandbox commands
   • State Management: Session-based storage with React hooks

2. Backend (FastAPI)

   • API Layer: RESTful endpoints for code generation and execution
   • Prompt Engine: Advanced prompt engineering for optimal AI responses
   • Parser Service: Extracts and organizes generated artifacts
   • Sandbox Manager: E2B sandbox lifecycle management

3. External Services

   • OpenAI GPT-4o: Primary language model for code generation
   • Anthropic Claude Sonnet 4: Alternative model with extended context
   • E2B Sandboxes: Isolated execution environments with Node.js support

---

Installation

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18.0.0 or higher) - Download
• Python (v3.9 or higher) - Download
• npm or yarn - Comes with Node.js
• Git - Download

API Keys Required

You'll need API keys from the following services:

1. OpenAI API Key - Get it here
2. Anthropic API Key - Get it here
3. E2B API Key - Get it here

Step-by-Step Setup

1. Clone the Repository

git clone https://github.com/idboussadel/codeforge.git
cd codeforge

2. Backend Setup

# Navigate to backend directory
cd backend

# Create a virtual environment (recommended)
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Create .env file
cp .env.example .env  # Or create manually

# Edit .env and add your API keys

Backend .env file:

OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
E2B_API_KEY=your_e2b_api_key_here

3. Frontend Setup

# Navigate to frontend directory (from project root)
cd frontend

# Install dependencies
npm install
# or
yarn install

# Create .env.local file (if needed for frontend-specific vars)
cp .env.example .env.local  # Optional

---

Configuration

Backend Configuration

File: backend/.env

# Required API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
E2B_API_KEY=...

# Optional: Server Configuration
HOST=0.0.0.0
PORT=8000

# Optional: Logging Level
LOG_LEVEL=ERROR  # ERROR, INFO, DEBUG

Frontend Configuration

File: frontend/.env.local (Optional)

# API Base URL (default: http://localhost:8000)
NEXT_PUBLIC_API_URL=http://localhost:8000

# Optional: Analytics, etc.

CORS Configuration

The backend is configured to allow requests from http://localhost:3000 by default. To modify:

File: backend/main.py

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],  # Modify this
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

---

Usage

Starting the Application

1. Start the Backend Server

cd backend

# Activate virtual environment if not already active
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Start FastAPI server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

The backend will be available at http://localhost:8000

2. Start the Frontend Development Server

cd frontend

# Start Next.js dev server
npm run dev
# or
yarn dev

The frontend will be available at http://localhost:3000

Using CodeForge

1. Open your browser and navigate to http://localhost:3000

2. Enter a prompt describing what you want to build:

   Create a modern landing page for a SaaS product with a hero section,
   feature cards, pricing table, and contact form. Use gradients and
   animations.
   

3. Select your AI model:

   • GPT-4o: Faster, great for most use cases
   • Claude Sonnet 4: Larger context window, better for complex apps

4. Watch the magic happen:

   • AI generates complete code with all necessary files
   • Preview updates in real-time as code is created
   • Interact with the generated application immediately

5. Iterate and refine:

   Add a dark mode toggle and make the pricing cards more vibrant
   

6. Execute terminal commands (if needed):

   • Use the terminal panel to run npm commands
   • Install additional packages
   • Check build outputs

---

API Reference

POST /api/generate

Generate code from a natural language prompt.

Request Body:

{
  "prompt": "Create a todo app with React",
  "conversation_history": [],
  "model_provider": "gpt"
}

Response:

{
  "content": "Full AI response with markdown and artifacts",
  "artifact": {
    "id": "unique-artifact-id",
    "title": "Todo Application",
    "type": "nextjs",
    "actions": [
      {
        "type": "file",
        "path": "package.json",
        "content": "..."
      }
    ]
  }
}

POST /api/stream

Stream code generation responses in real-time.

Request Body:

{
  "prompt": "Build a weather dashboard",
  "conversation_history": [],
  "model_provider": "claude"
}

Response: Server-Sent Events (SSE) stream

POST /api/execute

Execute artifact actions in an E2B sandbox.

Request Body:

{
  "session_id": "unique-session-id",
  "actions": [
    {
      "type": "file",
      "path": "app/page.tsx",
      "content": "export default function Page() { ... }"
    }
  ]
}

POST /api/terminal

Execute shell commands in the sandbox.

Request Body:

{
  "session_id": "unique-session-id",
  "command": "npm install axios"
}

---

Project Structure

codeforge/
├── backend/                    # FastAPI backend
│   ├── main.py                # Main API application
│   ├── prompts.py             # Prompt engineering templates
│   ├── requirements.txt       # Python dependencies
│   ├── .env                   # Environment variables (not in git)
│   └── services/              # Business logic services
│       ├── parser.py          # Artifact extraction & parsing
│       └── sandbox.py         # E2B sandbox management
│
├── frontend/                  # Next.js frontend
│   ├── app/                   # Next.js App Router
│   │   ├── page.tsx           # Landing page
│   │   ├── layout.tsx         # Root layout
│   │   ├── globals.css        # Global styles
│   │   └── chat/              # Chat interface
│   │       └── [id]/
│   │           └── page.tsx   # Dynamic chat page
│   │
│   ├── components/            # React components
│   │   ├── chat-panel.tsx     # Chat interface component
│   │   ├── preview-panel.tsx  # Code preview component
│   │   ├── terminal.tsx       # Terminal component
│   │   └── ui/                # shadcn/ui components
│   │       ├── button.tsx
│   │       ├── card.tsx
│   │       ├── input.tsx
│   │       └── ...
│   │
│   ├── lib/                   # Utilities & types
│   │   ├── api.ts             # API client functions
│   │   ├── types.ts           # TypeScript type definitions
│   │   └── utils.ts           # Utility functions
│   │
│   ├── public/                # Static assets
│   ├── package.json           # Node dependencies
│   ├── tsconfig.json          # TypeScript config
│   ├── tailwind.config.ts     # Tailwind configuration
│   └── next.config.ts         # Next.js configuration
│
├── .gitignore                 # Git ignore rules
└── README.md                  # This file

---

Development

Backend Development

Installing New Python Packages

cd backend
pip install package-name
pip freeze > requirements.txt

Running Tests

cd backend
pytest

Code Formatting

# Install black (code formatter)
pip install black

# Format code
black .

Frontend Development

Installing New NPM Packages

cd frontend
npm install package-name
# or
yarn add package-name

Type Checking

npm run type-check
# or
npx tsc --noEmit

Linting

npm run lint

Building for Production

npm run build
npm run start  # Run production build

Adding shadcn/ui Components

While CodeForge generates shadcn/ui components programmatically, you can add them manually:

cd frontend
npx shadcn@latest add button
npx shadcn@latest add card
# etc.

---

Deployment

Backend Deployment (FastAPI)

Option 1: Docker

FROM python:3.9-slim

WORKDIR /app
COPY backend/requirements.txt .
RUN pip install -r requirements.txt

COPY backend/ .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

docker build -t codeforge-backend .
docker run -p 8000:8000 --env-file backend/.env codeforge-backend

Option 2: Cloud Platforms

• Railway: Connect GitHub repo, set environment variables
• Render: Deploy as Web Service, add environment variables
• Google Cloud Run: Deploy container with Cloud Build
• AWS Lambda: Use Mangum adapter for serverless deployment

Frontend Deployment (Next.js)

Option 1: Vercel (Recommended)

cd frontend
npm install -g vercel
vercel

Option 2: Docker

FROM node:18-alpine

WORKDIR /app
COPY frontend/package*.json ./
RUN npm install

COPY frontend/ .
RUN npm run build

CMD ["npm", "start"]

Option 3: Static Export (if applicable)

npm run build
# Deploy the 'out' directory to any static host

Environment Variables in Production

Backend:

• Set OPENAI_API_KEY, ANTHROPIC_API_KEY, E2B_API_KEY in your hosting platform
• Update CORS origins in main.py to match your frontend URL

Frontend:

• Set NEXT_PUBLIC_API_URL to your backend URL
• Ensure API endpoint URLs are correctly configured

---

Troubleshooting

Common Issues

Issue: Backend won't start

Error: No module named 'fastapi'

Solution:

cd backend
pip install -r requirements.txt

Issue: Frontend API calls fail

Error: CORS policy blocked

Solution: Update backend/main.py CORS settings:

allow_origins=["http://localhost:3000", "your-frontend-url"]

Issue: E2B sandbox timeout

Error: Sandbox creation timeout

Solution:

• Check your E2B API key is valid
• Verify E2B account has available credits
• Check network connectivity

Issue: Module not found in generated code

Solution: The sandbox needs to install dependencies:

• Use the terminal panel to run npm install
• CodeForge automatically runs this in most cases

Issue: Preview not loading

Solution:

• Check browser console for errors
• Verify the sandbox URL is accessible
• Try refreshing the preview panel

Getting Help

• GitHub Issues: Open an issue
• Documentation: Check this README thoroughly
• Logs: Check backend terminal for detailed error messages

---

Contributing

We welcome contributions! Here's how you can help:

How to Contribute

1. Fork the repository

   git clone https://github.com/yourusername/codeforge.git

2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes

   • Write clean, documented code
   • Follow existing code style
   • Add tests if applicable

4. Commit your changes

   git commit -m "Add amazing feature"

5. Push to your fork

   git push origin feature/amazing-feature

6. Open a Pull Request

Development Guidelines

• Code Style: Follow PEP 8 for Python, ESLint config for TypeScript
• Commits: Use clear, descriptive commit messages
• Documentation: Update README if you change functionality
• Testing: Ensure existing tests pass, add tests for new features

Areas for Contribution

• Bug fixes
• New features (AI models, UI improvements)
• Documentation improvements
• UI/UX enhancements
• Test coverage
• Internationalization

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Acknowledgments

• OpenAI - For the powerful GPT-4o model
• Anthropic - For Claude Sonnet 4
• E2B - For secure sandbox environments
• Vercel - For Next.js and deployment platform
• shadcn - For the beautiful UI component library
• FastAPI - For the modern Python web framework

---

Contact

Project Maintainer: @idboussadel

Project Link: https://github.com/idboussadel/codeforge

---

Made with love by developers, for developers

Star this repo if you find it helpful!